Functions

LLVM.Function

A function in the IR.

Properties

f.function_type

The function type of the function, as opposed to the value_type property, which is the pointer type of the function constant.

f.personality
f.personality = persfn::Union{LLVM.Constant,Nothing}

The personality function of the function, or nothing if it has none. Assigning nothing removes the personality function.

The personality is usually a Function, but can be any constant referring to one, such as a GlobalAlias or a constant expression (e.g., a bitcast when using typed pointers).

f.callconv
f.callconv = cc

The calling convention of the function, e.g., LLVM.CallConv.Fast.

f.gc
f.gc = name::AbstractString

The name of the garbage collector of the function, or an empty string if it has none.

f.alignment
f.alignment = bytes::Integer

The alignment of the code of the function 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.

f.entry

The entry basic block of the function, or nothing if the function has no body.

f.function_attributes

The attributes of the function itself, as a mutable view that can be iterated, and supports push!, append! and delete!. Adding an attribute replaces any existing attribute of the same kind. The view can also be indexed by the kind of an attribute: a Symbol for LLVM's attribute kinds, and a string for string attributes, e.g., haskey(f.function_attributes, :nounwind), f.function_attributes["target-cpu"] or delete!(f.function_attributes, :noinline).

See also the return_attributes and parameter_attributes properties.

f.parameter_attributes

The attributes of the parameters of the function, as a vector with a view of the attributes of each parameter. These views work like the function_attributes of the function, e.g., push!(f.parameter_attributes[1], EnumAttribute("nocapture")).

f.return_attributes

The attributes of the return value of the function, as a mutable view that works like the function_attributes of the function.

f.memory_effects
f.memory_effects = effects::Union{MemoryEffects,FunctionMemoryEffects}

The memory effects of the function, as described by its memory attribute, or MemoryEffects(:readwrite) if it doesn't have one. The effects are returned as a FunctionMemoryEffects view, which can be used to change the access kind of a single location, e.g., f.memory_effects[:argmem] = :read. Assigning adds a memory attribute, replacing any existing one. On LLVM 15, this uses the attributes that the memory attribute replaced, which can't represent all effects (see MemoryEffects).

See also: MemoryEffects

f.parameters

The parameters of the function, as a read-only view. These are Argument values that can be used as inputs to other instructions.

f.blocks

The basic blocks of the function, in order, as a read-only view that always reflects the current body of the function. Create a BasicBlock to add one, and use operations like remove! or move! to change the list of blocks. Indexing the view walks the list of blocks, so iterate instead of indexing each block. While iterating over the view, it is safe to remove or erase the block that was just returned, but not other blocks.

f.subprogram
f.subprogram = sp::Union{DISubprogram,Nothing}

The subprogram that describes the function, or nothing if it has none. Assigning nothing removes it.

f.intrinsic

The intrinsic that the function declares, or nothing if it isn't an intrinsic.

f.next
f.prev

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

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

LLVM.Function(mod::Module, name::AbstractString, ft::FunctionType)

Create a new function in the given module with the given name and function type.

LLVM.Argument

A parameter of a function, as a value that can be used in its body.

Properties

arg.parent

The function that the parameter belongs to.

arg.index

The position of the parameter in the parameter list of its function, starting at 1, so that arg.parent.parameters[arg.index] == arg.

arg.next
arg.prev

The next or previous parameter of the function, or nothing if there is none.

The properties of Value are available too.

copy_attributes!(dest::LLVM.Function, src::LLVM.Function)
copy_attributes!(dest::GlobalVariable, src::GlobalVariable)

Copy the attributes of src that are not needed to create it to dest, like C++'s copyAttributesFrom, e.g., when replacing a function by one with a different signature. This copies the visibility, DLL storage class, unnamed_addr, thread-local mode, alignment and section, and for functions also the calling convention, garbage collector, personality, and function, return and parameter attributes, and for global variables whether they are externally initialized, their attributes and code model. Returns dest.

The name, linkage, body or initializer, and metadata are not copied. Parameter attributes are copied by position, so if the parameters of dest differ from those of src, fix up dest.parameter_attributes afterwards. COMDAT is not copied. If the source has no personality, prefix or prologue data, those fields on the destination are left as they were.

empty!(f::Function)

Delete the body of the given function, and convert the linkage to external.

empty!(jd::JITDylib)

Remove all code and data from jd, releasing the resources of all of its resource trackers.

erase!(f::Function)

Remove the given function from its parent module and free the object.

Attribute

An attribute of a function, of its return value or one of its parameters, or of a call site. Attributes are immutable, and are created using one of the constructors of its subtypes: EnumAttribute, TypeAttribute, StringAttribute, or ConstantRangeAttribute (LLVM 19+).

Properties

attr.kind

The kind of the attribute: a Symbol naming one of LLVM's attribute kinds (like :nounwind or :align) for enum, type and constant range attributes, or the String name of a string attribute. Attribute sets can be indexed by this kind, e.g., f.function_attributes[attr.kind].

attr.value

The value of the attribute: an integer for enum attributes (0 if the attribute has no value), a string for string attributes, and a type for type attributes. Constant range attributes do not have this property, as the C API cannot read their value.

EnumAttribute(kind::Symbol, value::Integer=0)

Create an attribute of one of LLVM's attribute kinds, e.g., EnumAttribute(:nounwind) or EnumAttribute(:align, 16). Only kinds that take an integer, like align, can have a value. Attributes that carry a type, like sret, are created using TypeAttribute instead. The kind can also be passed as a String.

TypeAttribute(kind::Symbol, value::LLVMType)

Create an attribute of one of LLVM's attribute kinds that carries a type, e.g., TypeAttribute(:sret, T) or TypeAttribute(:byval, T). The kind can also be passed as a String.

StringAttribute(kind::AbstractString, value::AbstractString="")

Create a string attribute, identified by an arbitrary name, and optionally carrying a string value. These are used for target-specific attributes like "target-cpu", or for information that a compiler wants to attach to IR.

ConstantRangeAttribute <: Attribute
ConstantRangeAttribute(kind, nbits::Integer, lower::AbstractVector{UInt64},
                       upper::AbstractVector{UInt64})

An attribute whose value is a range of integers of nbits bits, like range, from lower (inclusive) to upper (exclusive), given as the 64-bit words of the bounds (least significant first). Creating one requires LLVM 19+.

ConstantRangeListAttribute <: Attribute

An attribute whose value is a list of ranges of integers, like initializes (LLVM 20+). They can't be created using LLVM's C API.

MemoryEffects(default::Symbol=:none; argmem, inaccessiblemem, errnomem, other, ...)

The memory effects of a function or call, i.e., the kind of access that may happen to each location of memory. These effects are encoded in the memory attribute, which since LLVM 16 replaces the readnone, readonly, writeonly, argmemonly, inaccessiblememonly and inaccessiblemem_or_argmemonly function attributes. Use EnumAttribute(effects) to create that attribute and MemoryEffects(attrs) to decode it from a set of function or call attributes, or the memory_effects property of a function to get and set it directly. That property returns a FunctionMemoryEffects view, which MemoryEffects(effects) converts to a value.

The access kind of every location is one of :none, :read, :write or :readwrite, and defaults to default. The locations are:

• argmem: memory accessed through pointer arguments;
• inaccessiblemem: memory that is not accessible by the current module;
• errnomem: the errno variable (LLVM 21 and later, before that part of other);
• target_mem0, target_mem1: target-specific state (LLVM 22 and later, experimental);
• other: any other memory.

These effects are an upper bound: an access kind like :read does not guarantee that a read happens. The access kind of a single location can be queried by indexing, e.g., effects[:argmem], while the access property returns the access kind for all locations combined. Effects can be combined with | (union) and & (intersection).

Examples

MemoryEffects(:none)                    # memory(none), formerly `readnone`
MemoryEffects(:read)                    # memory(read), formerly `readonly`
MemoryEffects(argmem=:readwrite)        # memory(argmem: readwrite), formerly `argmemonly`
MemoryEffects(:read; argmem=:readwrite) # memory(read, argmem: readwrite)

Properties

effects.access

The kind of memory access that is possible for any location: :none if no memory may be accessed, :read if it may only be read, :write if it may only be written, and :readwrite otherwise.

FunctionMemoryEffects

The memory effects of a function or a call, as returned by their memory_effects property. This is a view of the memory attribute in their function attributes, which supports the same operations as a MemoryEffects value: indexing (effects[:argmem]), the access property, | and &, and comparing to other effects. In addition, the access kind of a single location can be changed in place, which replaces the memory attribute:

f.memory_effects[:argmem] = :read

Use MemoryEffects(effects) to get the current effects as a value, which doesn't change along with the function or call.

EnumAttribute(effects::MemoryEffects)

Create a memory attribute describing the given memory effects.

LLVM.memory_attributes(effects::Union{MemoryEffects,FunctionMemoryEffects})

Create the attributes that describe the memory effects of a function or call, on any version of LLVM: the memory attribute on LLVM 16 and later, or the attributes that it replaced on LLVM 15 (none for unrestricted effects). This is for building lists of attributes, e.g., for a function declaration; on LLVM 15, it throws an ArgumentError for effects that can't be represented (see MemoryEffects).

Adding these attributes to a function or call doesn't remove the ones that describe other effects on LLVM 15. To replace the memory effects of a function or call, assign its memory_effects property instead.

LLVM.Intrinsic
Intrinsic(name::AbstractString)
Intrinsic(f::LLVM.Function)

An LLVM intrinsic function, identified by its (base) name, e.g., Intrinsic("llvm.memcpy"), or the intrinsic that a function declares. Throws an ArgumentError if there is no such intrinsic; use tryparse to look up a name that the version of LLVM in use may not know, and the intrinsic property of functions to check whether a function is an intrinsic.

Properties

intr.name

The name of the intrinsic. For overloaded intrinsics, this is the base name, e.g., llvm.sin; see LLVM.overloaded_name to get the name of a specific overload.

tryparse(LLVM.Intrinsic, name::AbstractString)

Look up the intrinsic with the given name, like Intrinsic(name), but return nothing if the version of LLVM in use doesn't know it. The name can be the base name of an overloaded intrinsic (e.g., "llvm.sin") or the name of an overload (e.g., "llvm.sin.f64"), as LLVM recognizes them.

parse(LLVM.Intrinsic, name::AbstractString)

Look up the intrinsic with the given name, throwing an ArgumentError if the version of LLVM in use doesn't know it. This is the same as Intrinsic(name).

isintrinsic(val::Value)
isintrinsic(val::Value, intr::Intrinsic)

Check if the given value is a function that is an intrinsic, or a specific intrinsic. This works with any value, e.g., to check the called_operand of a call instruction:

memcpy = Intrinsic("llvm.memcpy")
isintrinsic(call.called_operand, memcpy)

Intrinsics are identified by their ID, so unlike C++'s Function::isIntrinsic, which checks for the llvm. prefix that is reserved for intrinsics, this is false for functions that are named like intrinsics that the current version of LLVM does not know.

isoverloaded(intr::Intrinsic)

Check if the given intrinsic is overloaded.

LLVM.overloaded_name(intr::LLVM.Intrinsic, params::AbstractVector{<:LLVMType})

Get the name of the given overloaded intrinsic with the given parameter types, e.g., llvm.sin.f64. Without types, this is the base name of the intrinsic, like intr.name. Throws an ArgumentError if the intrinsic isn't overloaded.

Function(mod::Module, intr::Intrinsic, params::AbstractVector{<:LLVMType}=LLVMType[])

Get the declaration of the given intrinsic in the given module. For an overloaded intrinsic, params are the types of its overloaded parameters, in the order of the name of the overload: e.g., [ptr, ptr, i64] for llvm.memcpy.p0.p0.i64. Other intrinsics take no types. Whether the intrinsic is overloaded can differ between versions of LLVM (e.g., llvm.va_start is overloaded since LLVM 19), which isoverloaded checks.

Throws an ArgumentError if types are given for an intrinsic that isn't overloaded, or none for one that is. Other mismatches aren't detected: extra types end up in the name of the declaration, and missing ones crash LLVM.

FunctionType(intr::Intrinsic, params::AbstractVector{<:LLVMType}=LLVMType[])

Get the function type of the given intrinsic with the given types of its overloaded parameters, like for LLVM.Function(mod, intr, params), which describes how they're checked.