Values

LLVM.Value

Abstract type representing an LLVM value.

Properties

bb.name
bb.name = name::AbstractString

The name of the basic block, like that of other values.

val.value_type

The type of the value.

val.name
val.name = name::AbstractString

The name of the value, or an empty string if it is unnamed. When assigning a name that is already in use in the same function or module, LLVM makes it unique by adding a suffix.

val.context

The context in which the value was created.

val.uses

The uses of the value, as a read-only view that can be iterated. Each LLVM.Use refers to the user that has the value as an operand. Since LLVM 21, constants like integers do not keep track of their uses, so their uses are always empty.

val.users

The users of the value, i.e., the user of each of its uses, as a read-only view that can be iterated. Like C++'s Value::users(), a user that uses the value multiple times (e.g., add %x, %x) occurs multiple times.

isconstant(val::LLVM.Value)

Check if the given value is a constant value.

isundef(val::LLVM.Value)

Check if the given value is an undef value.

ispoison(val::LLVM.Value)

Check if the given value is a poison value.

isnull(val::LLVM.Value)

Check if the given value is a null constant.

take_name!(val::Value, from::Value)

Give val the name of from, which becomes unnamed. Unlike assigning the name, this avoids LLVM making the name unique (by adding a suffix) because from still uses it.

strip_pointer_casts(val::Value)

Strip pointer casts from a value, like C++'s Value::stripPointerCasts: bitcasts, address space casts, and getelementptr instructions or constant expressions with all-zero indices. Returns the underlying value, or val itself if it isn't a cast. This does not look through global aliases; see strip_pointer_casts_and_aliases for that.

strip_pointer_casts_and_aliases(val::Value)

Strip pointer casts from a value, like strip_pointer_casts, and also look through global aliases to the value they alias.

LLVM.User <: LLVM.Value

A value that uses other values.

See also the operands property.

Properties

user.operands

The operands of a user, e.g., an instruction or a constant expression, as a view. For instructions and global values, the view is mutable: assigning to an element, inst.operands[i] = val, replaces that operand, and replace!(inst.operands, old => new) replaces every operand that is old. The operands of other constants cannot be changed, as LLVM uniques constants by their operands; use replace_uses! on the operand to update the constants that use it instead.

The properties of Value are available too.

LLVM.Constant <: LLVM.User

Abstract supertype for all constant values.

null(typ::LLVMType)

Create a null constant of the given type.

all_ones(typ::LLVMType)

Create a constant with all bits set to one of the given type.

PointerNull <: LLVM.ConstantData

A null pointer constant.

UndefValue <: LLVM.ConstantData

An undefined constant value.

PoisonValue <: LLVM.ConstantData

A poison constant value.

ConstantInt <: LLVM.ConstantData

A constant integer value.

convert(::Type{<:Integer}, val::ConstantInt)

Convert a constant integer value back to a Julia integer.

ConstantFP <: LLVM.ConstantData

A constant floating point value.

Properties

val.bitpattern

The bit pattern of a constant floating point value, as the smallest unsigned integer that can hold it (e.g., UInt32 for float, or UInt128 for x86_fp80).

See also ConstantFP, which can create a constant from its bit pattern.

The properties of User and Value are available too.

convert(::Type{<:AbstractFloat}, val::ConstantFP)

Convert a constant floating point value back to a Julia floating point number.

ConstantStruct <: LLVM.ConstantAggregate

A constant struct of values.

LLVM.ConstantDataSequential <: LLVM.Constant

Abstract supertype of constant arrays and vectors of simple data values: ConstantDataArray and ConstantDataVector.

ConstantDataArray <: LLVM.ConstantDataSequential

A constant array of simple data values, i.e., whose element type is a simple 1/2/4/8-byte integer or half/bfloat/float/double, and whose elements are just simple data values. Its elements are available as the elements property, see LLVM.ConstantAggregate.

See also: ConstantArray

ConstantDataArray(typ::LLVMType, data::AbstractVector)

Create a constant array of simple data values of the given type and data.

The element type needs to be a 1/2/4/8-byte integer or a half/bfloat/float/double type, of the same size as the elements of data, whose bits are used as-is.

ConstantDataArray(data::AbstractVector)

Create a constant array of simple data values from a Julia vector.

isstring(val::Value)

Check whether the given value is a constant string, i.e., a constant array of i8 values, like C++'s ConstantDataSequential::isString. Its contents can be retrieved using String.

String(str::ConstantDataArray)

Get the contents of a constant string, like C++'s ConstantDataSequential::getAsString. This includes all NUL characters, e.g., the one that terminates a C string. Throws an ArgumentError if the array is not a string; see isstring.

ConstantDataVector <: LLVM.ConstantDataSequential

A constant vector of simple data values, i.e., whose element type is a simple 1/2/4/8-byte integer or half/bfloat/float/double, and whose elements are just simple data values. Its elements are available as the elements property, see LLVM.ConstantAggregate.

ConstantArray <: LLVM.ConstantAggregate

A constant array of values. Its elements are available as the elements property, see LLVM.ConstantAggregate.

ConstantArray(typ::LLVMType, data::AbstractArray)

Create a constant array of values of the given type and data.

ConstantArray(data::AbstractArray)

Create a constant array of values from a Julia array, using the appropriate constant type.

ConstantVector <: LLVM.ConstantAggregate

A constant vector of other constants, which LLVM creates for vectors whose elements aren't simple data values (see ConstantDataVector). Its elements are available as the elements property, see LLVM.ConstantAggregate.

ConstantAggregateZero <: LLVM.ConstantData

The zeroinitializer of an array, structure or vector type, as created by null or by LLVM for aggregates whose elements are all zero. Its elements are available as the elements property, see LLVM.ConstantAggregate.

LLVM.ConstantAggregate <: LLVM.Constant

Abstract supertype of constant arrays, structs and vectors whose elements are other constants: ConstantArray, ConstantStruct and ConstantVector.

Properties

c.elements

The elements of an aggregate constant, as a read-only vector of constants, e.g., i32 2 for the second element of [3 x i32] [i32 1, i32 2, i32 3]. This property is also available for arrays and vectors of simple data (ConstantDataArray and ConstantDataVector) and for zeroinitializer (ConstantAggregateZero), which LLVM uses to represent aggregate constants whose elements are simple data or zero. Nested aggregates are elements themselves, i.e., the elements of a constant of type [2 x [2 x i32]] are two constants of type [2 x i32].

The properties of User and Value are available too.

InlineAsm <: LLVM.Constant

A constant inline assembly block.

BlockAddress <: LLVM.Constant

The address of a basic block, blockaddress(@f, %bb) in LLVM IR, e.g., as the destination of an indirectbr instruction.

Properties

ba.function

The function that contains the basic block.

ba.block

The basic block whose address this is.

The properties of User and Value are available too.

BlockAddress(bb::BasicBlock)

Get the address of the basic block bb, which must be part of a function. Taking the address of the entry block of a function is not valid IR.

ConstantTokenNone <: LLVM.ConstantData

The none token, e.g., the parent pad of a cleanuppad or catchswitch instruction that is not nested in another pad. It is the null value of the token type, so it is created using null(LLVM.TokenType()).

ConstantTargetNone <: LLVM.ConstantData

The zeroinitializer of a target extension type (e.g., target("spirv.Event")), which only exists on LLVM 16 and later.

ConstantPtrAuth <: LLVM.Constant

A signed pointer, ptrauth (ptr @f, i32 0) in LLVM IR, as used for pointer authentication (e.g., on arm64e). This constant only exists on LLVM 19 and later.

convert_users_to_instructions!(consts::AbstractVector{<:Constant};
                               func::Union{Nothing,LLVM.Function}=nothing,
                               remove_dead_constants::Bool=true,
                               include_self::Bool=false) -> Bool

Rewrite every constant expression or constant aggregate that (transitively) uses one of consts into equivalent instructions at each point of use; phi operands are materialized in their incoming block. Returns whether anything changed.

Optionally restrict the rewrite to func, keep dead constants around (remove_dead_constants=false), or also convert the passed constants themselves (include_self=true). These three options require LLVM 19 or later; the function itself requires LLVM 17 or later.

remove_dead_constant_users!(c::Constant)

Remove the constants that use c, directly or transitively, but are not used themselves, like C++'s Constant::removeDeadConstantUsers. These are, e.g., constant expressions that remain after replacing or erasing the instructions that used them, and that keep c from being unused. c itself is not removed. Returns c.

LLVM.ConstantExpr <: LLVM.Constant

A constant value that is initialized with an expression using other constant values.

Constant expressions are created using const_-prefixed functions, which correspond to the LLVM IR instructions: const_neg, const_not, etc.

Properties

ce.opcode

The opcode of the constant expression, e.g., LLVM.Opcode.Add.

ce.source_element_type

The type that a getelementptr constant expression indexes into. Throws an ArgumentError for other constant expressions.

ce.indices

The indices of a getelementptr constant expression, i.e., its operands after the pointer, as a read-only view. Throws an ArgumentError for other constant expressions.

The properties of User and Value are available too.

const_add(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression add of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_addrspacecast(val::Constant, dest_type::LLVMType) -> Constant

Create the constant expression that converts val to dest_type using a addrspacecast. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_bitcast(val::Constant, dest_type::LLVMType) -> Constant

Create the constant expression that converts val to dest_type using a bitcast. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_extractelement(vec::Constant, index::Constant) -> Constant

Create the constant expression extractelement of the element at the 0-based index of vec. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_icmp(predicate::LLVM.IntPredicate.T, lhs::Constant, rhs::Constant)
    -> Constant
const_fcmp(predicate::LLVM.RealPredicate.T, lhs::Constant, rhs::Constant)
    -> Constant

Create the constant expression icmp or fcmp that compares lhs and rhs using predicate. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_gep(type::LLVMType, ptr::Constant, indices::AbstractVector{<:Constant})
    -> Constant
const_inbounds_gep(type::LLVMType, ptr::Constant,
                   indices::AbstractVector{<:Constant}) -> Constant

Create the constant expression getelementptr (or getelementptr inbounds) that computes the address of an element of the value of type at ptr, using the 0-based indices. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_icmp(predicate::LLVM.IntPredicate.T, lhs::Constant, rhs::Constant)
    -> Constant
const_fcmp(predicate::LLVM.RealPredicate.T, lhs::Constant, rhs::Constant)
    -> Constant

Create the constant expression icmp or fcmp that compares lhs and rhs using predicate. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_gep(type::LLVMType, ptr::Constant, indices::AbstractVector{<:Constant})
    -> Constant
const_inbounds_gep(type::LLVMType, ptr::Constant,
                   indices::AbstractVector{<:Constant}) -> Constant

Create the constant expression getelementptr (or getelementptr inbounds) that computes the address of an element of the value of type at ptr, using the 0-based indices. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_insertelement(vec::Constant, elt::Value, index::Constant) -> Constant

Create the constant expression insertelement that replaces the element at the 0-based index of vec by elt. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_inttoptr(val::Constant, dest_type::LLVMType) -> Constant

Create the constant expression that converts val to dest_type using a inttoptr. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_mul(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression mul of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_neg(val::Constant) -> Constant

Create the constant expression sub 0, val. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_not(val::Constant) -> Constant

Create the constant expression xor val, -1. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_nswadd(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression add nsw of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_nswmul(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression mul nsw of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_nswneg(val::Constant) -> Constant

Create the constant expression sub nsw 0, val. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_nswsub(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression sub nsw of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_nuwadd(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression add nuw of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_nuwmul(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression mul nuw of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_nuwsub(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression sub nuw of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_pointercast(val::Constant, dest_type::LLVMType) -> Constant

Create the constant expression that converts val to dest_type using a pointer cast (bitcast, addrspacecast or ptrtoint). LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_ptrtoint(val::Constant, dest_type::LLVMType) -> Constant

Create the constant expression that converts val to dest_type using a ptrtoint. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_shl(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression shl of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_shufflevector(v1::Constant, v2::Constant, mask::Constant) -> Constant

Create the constant expression shufflevector of v1 and v2, using the constant vector mask. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_splat(typ::LLVM.VectorType, value::Constant)
const_splat(typ::LLVM.VectorType, value::Real)

Create a constant vector of type typ whose elements are all value, which must be a constant of the element type of typ, or a Julia number that is converted to one: using ConstantFP for a vector of floating-point values, or ConstantInt for a vector of integers, which requires an Integer. For example, to create a vector of floating-point ones:

const_splat(LLVM.VectorType(LLVM.FloatType(), 4), 1)

The result is the constant that LLVM uses to represent the splat, e.g., a ConstantDataVector, or a ConstantAggregateZero for zeros, so it is only guaranteed to be a Constant.

const_sub(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression sub of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_trunc(val::Constant, dest_type::LLVMType) -> Constant

Create the constant expression that converts val to dest_type using a trunc. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_truncorbitcast(val::Constant, dest_type::LLVMType) -> Constant

Create the constant expression that converts val to dest_type using a trunc (or bitcast, if the types have the same size). LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

const_type!(builder::DIBuilder, type::DIType) -> DIDerivedType

Create a const-qualified type. Shorthand for qualified_type!(builder, DW_TAG_const_type, type).

const_xor(lhs::Constant, rhs::Constant) -> Constant

Create the constant expression xor of lhs and rhs. LLVM folds the expression if it can, so the result is a Constant, not necessarily a ConstantExpr.

LLVM.GlobalValue <: LLVM.Constant

Abstract supertype for all global values.

Properties

gv.parent

The module that contains the global value.

gv.global_value_type

The type of the global value.

This differs from the value_type property in that it is the type of the contained value, not the type of the global value itself, which is always a pointer type.

gv.linkage
gv.linkage = linkage::LLVM.Linkage.T

The linkage of the global value.

gv.section
gv.section = section::AbstractString

The section of the global value, or an empty string if it isn't placed in a specific section. Only global objects (functions, global variables and ifuncs) can be assigned a section: the section of an alias is that of its aliasee, and cannot be changed.

gv.visibility
gv.visibility = visibility::LLVM.Visibility.T

The visibility of the global value.

gv.dllstorage
gv.dllstorage = storage::LLVM.DLLStorageClass.T

The DLL storage class of the global value.

gv.unnamed_addr
gv.unnamed_addr = kind::LLVM.UnnamedAddr.T

Whether the address of the global value is significant: LLVM.UnnamedAddr.No if it is, LLVM.UnnamedAddr.Local if it is insignificant within the module (local_unnamed_addr), and LLVM.UnnamedAddr.Global if it is insignificant altogether (unnamed_addr), which allows merging it with other constants that have the same initializer.

The properties of User and Value are available too.

LLVM.GlobalObject <: LLVM.GlobalValue

Abstract supertype for global values that are backed by an actual object in memory, i.e., functions, global variables and ifuncs, but not aliases.

Properties

inst.metadata
gv.metadata

The metadata attached to an instruction or a global object (a function or global variable), as a dictionary-like view that maps the kind of metadata to a metadata node. The kind can be an MDKind, like LLVM.MD_dbg, or the name of the kind, like "tbaa". The view can be iterated (in the case of an instruction, this includes its debug location), and is mutable: assign to a kind to attach metadata, e.g., inst.metadata["tbaa"] = node, and use delete! to remove it.

The properties of GlobalValue, User and Value are available too.

isdeclaration(val::LLVM.GlobalValue)

Check if the global value is a declaration, i.e. it does not have a definition.

GlobalVariable <: LLVM.GlobalObject

A global variable.

Properties

gv.initializer
gv.initializer = val::Union{LLVM.Constant,Nothing}

The initializer of the global variable, or nothing if it has none (i.e., if it is a declaration). Assigning nothing removes the current initializer.

gv.threadlocal
gv.threadlocal = flag::Bool

Whether the global variable is thread-local. This is a view of the threadlocal_mode property: assigning true to a variable that is not thread-local selects the general dynamic model, while assigning false makes the variable not thread-local. Assigning the current value does not change the thread-local mode.

gv.constant
gv.constant = flag::Bool

Whether the global variable is a global constant, i.e., whether its value is immutable throughout the runtime execution of the program.

This differs from isconstant(gv), which checks whether a value is an LLVM constant, and is true for every global variable (which represents a constant address).

gv.threadlocal_mode
gv.threadlocal_mode = mode::LLVM.ThreadLocalMode.T

The thread-local storage model of the global variable, e.g., LLVM.ThreadLocalMode.GeneralDynamic, or LLVM.ThreadLocalMode.NotThreadLocal if it is not thread-local. See also the threadlocal property.

gv.externally_initialized
gv.externally_initialized = flag::Bool

Whether the global variable is externally initialized, i.e., whether its value may be changed before the program starts running, so that optimizations cannot rely on its initializer.

gv.alignment
gv.alignment = bytes::Integer

The alignment of the global variable in bytes, or 0 if it has no explicit alignment. The assigned alignment must be a power of 2, or 0 to remove the explicit alignment.

gv.next
gv.prev

The next or previous global variable in the module, or nothing if there is none.

The properties of GlobalObject, GlobalValue, User and Value are available too.

erase!(gv::GlobalVariable)

Remove the global variable from its parent module and delete it.

GlobalAlias <: LLVM.GlobalValue

A global alias, i.e., a new symbol for an existing global value or constant expression.

Properties

alias.aliasee
alias.aliasee = val::LLVM.Constant

The value that the global alias refers to. The type of an assigned value must match that of the alias.

alias.next
alias.prev

The next or previous global alias in the module, or nothing if there is none.

The properties of GlobalValue, User and Value are available too.

GlobalIFunc <: LLVM.GlobalObject

An indirect function, whose address is determined at load time by calling a resolver function.

Properties

ifunc.resolver
ifunc.resolver = val::LLVM.Constant

The resolver of the ifunc. The type of an assigned value must be a pointer in the address space of the ifunc.

ifunc.next
ifunc.prev

The next or previous ifunc in the module, or nothing if there is none.

The properties of GlobalObject, GlobalValue, User and Value are available too.

erase!(ifunc::GlobalIFunc)

Remove the ifunc from its parent module and delete it.

replace_uses!(old::LLVM.Value, new::LLVM.Value)

Replace all uses of an old value in the IR with new.

This does not replace uses in metadata, which must be done separately with replace_metadata_uses!.

replace_metadata_uses!(old::LLVM.Value, new::LLVM.Value)

Replace all uses of an old value in metadata with new. Before LLVM 18, the values need to have the same type, unless both are global values (e.g., when replacing a function by one with another signature, using typed pointers).

LLVM.Use

A use of a value in the IR, with properties for both the user and the used value.

Properties

use.user

The user of the use, i.e., the value that has the used value as an operand.

use.value

The used value of the use.