Code generation

Target

A structure exposing target-specific information.

Properties

target.name

The name of the target, e.g., "x86-64".

target.description

A short description of the target.

hasjit(target::Target)

Check if this targets supports the just-in-time compilation.

hastargetmachine(target::Target)

Check if this target supports code generation.

hasasmbackend(target::Target)

Check if this target has an assembly backend, which emits object files.

targets()

Get an iterator over the available targets.

LLVM.Triple(str::AbstractString)

A target triple, like x86_64-unknown-linux-gnu, interpreted by the loaded LLVM library like C++'s llvm::Triple. The string is used as it is, like C++ passes do with Triple(M.getTargetTriple()): spellings that LLVM only understands after normalization, like the OS of x86_64-w64-mingw32, are not recognized. Use normalize to get a normalized triple.

Two triples are equal if they are spelled the same. string(triple) returns the string.

Properties

triple.arch
triple.vendor
triple.os
triple.environment
triple.object_format

The architecture, vendor, operating system, environment and object file format that LLVM derives from the triple, as symbols named like LLVM does (e.g., :x86_64, :i386, :aarch64, :apple, :linux, :windows, :gnu, :elf, :macho, :coff), or :unknown. The names come from the loaded LLVM library, so other versions of LLVM may know about more of them, or name them differently (e.g., the architecture of amdgcn-amd-amdhsa is :amdgcn before LLVM 23, and :amdgpu since). The predicates below don't depend on such names. The object format defaults to the one of the operating system when the triple doesn't specify it, so triple.object_format == :elf is C++'s isOSBinFormatELF().

See also: isx86, isaarch64, isarm, isthumb, isriscv, isppc, isnvptx, isamdgpu, isspirv, iswasm, isdarwin, iswindows, islinux.

normalize(triple::LLVM.Triple)

Normalize the given target triple, e.g., turning x86_64-w64-mingw32 into x86_64-w64-windows-gnu.

LLVM.isx86(triple::LLVM.Triple)

Check whether the target triple is for 32- or 64-bit x86 (C++'s isX86), according to the loaded LLVM library.

LLVM.isaarch64(triple::LLVM.Triple)

Check whether the target triple is for AArch64, in any endianness or pointer size (C++'s isAArch64), according to the loaded LLVM library.

LLVM.isarm(triple::LLVM.Triple)

Check whether the target triple is for 32-bit ARM, not Thumb (C++'s isARM), according to the loaded LLVM library.

LLVM.isthumb(triple::LLVM.Triple)

Check whether the target triple is for Thumb (C++'s isThumb), according to the loaded LLVM library.

LLVM.isriscv(triple::LLVM.Triple)

Check whether the target triple is for 32- or 64-bit RISC-V (C++'s isRISCV), according to the loaded LLVM library.

LLVM.isppc(triple::LLVM.Triple)

Check whether the target triple is for 32- or 64-bit PowerPC, in any endianness (C++'s isPPC), according to the loaded LLVM library.

LLVM.isnvptx(triple::LLVM.Triple)

Check whether the target triple is for NVPTX (C++'s isNVPTX), according to the loaded LLVM library.

LLVM.isamdgpu(triple::LLVM.Triple)

Check whether the target triple is for AMDGPU, i.e., AMDGCN or R600 (C++'s isAMDGPU), according to the loaded LLVM library.

LLVM.isspirv(triple::LLVM.Triple)

Check whether the target triple is for SPIR-V (C++'s isSPIRV), according to the loaded LLVM library.

LLVM.iswasm(triple::LLVM.Triple)

Check whether the target triple is for WebAssembly (C++'s isWasm), according to the loaded LLVM library.

LLVM.isdarwin(triple::LLVM.Triple)

Check whether the target triple is for a Darwin operating system, like macOS or iOS (C++'s isOSDarwin), according to the loaded LLVM library.

LLVM.iswindows(triple::LLVM.Triple)

Check whether the target triple is for Windows (C++'s isOSWindows), according to the loaded LLVM library.

LLVM.islinux(triple::LLVM.Triple)

Check whether the target triple is for Linux (C++'s isOSLinux), according to the loaded LLVM library.

TargetMachine

Primary interface to the complete machine description for the target machine.

All target-specific information should be accessible through this interface.

Properties

tm.target

The target of the target machine.

tm.triple

The target triple of the target machine.

tm.cpu

The CPU of the target machine.

tm.features

The feature string of the target machine.

Ownership

A target machine is consumed by TargetMachineBuilder(tm), and thus by LLJIT(; tm), which take ownership of it. A consumed target machine can't be used anymore, and disposing of it does nothing, so that it can be disposed of unconditionally, e.g., using the do-block form of its constructor.

dispose(tm::TargetMachine)

Dispose of the given target machine, unless it has been consumed.

LLVM.default_triple()

Get the default target triple, i.e., the triple of the host that LLVM was configured for.

LLVM.host_cpu_name()

Get the name of the CPU of the host, e.g., "znver4", for use with a TargetMachine.

LLVM.host_cpu_features()

Get the features of the CPU of the host, as a string of comma-separated features that are enabled (+feature) or disabled (-feature), for use with a TargetMachine.

normalize(triple::AbstractString)

Normalize the given target triple.

asm_verbosity!(tm::TargetMachine, verbose::Bool)

Set the verbosity of the target machine's assembly output.

emit(tm::TargetMachine, mod::Module, filetype::LLVMCodeGenFileType) -> UInt8[]

Generate code for the given module using the target machine, returning the binary data. If assembly code was requested, the binary data can be converted back using String.

emit(tm::TargetMachine, mod::Module, filetype::LLVMCodeGenFileType,
     path::AbstractString)

Generate code for the given module using the target machine, writing it to the given file.

JITTargetMachine(; triple=LLVM.default_triple(), cpu="", features="",
                 opt_level=LLVM.CodeGenOptLevel.Default)
JITTargetMachine(f; kwargs...)

Create a target machine suitable for JIT compilation with the ORC JIT: like a TargetMachine, but with the static relocation model and the JIT's default code model, and an ELF triple on Windows.

This object needs to be disposed of using dispose, or by using the do-block form.

LLVM.SubtargetInfo

The CPU and features of a target, as LLVM's tables for that target describe them (C++'s MCSubtargetInfo). Enabling a feature also enables the features that it implies, and disabling a feature also disables the features that imply it; when a feature string sets a feature more than once, the last setting wins.

Properties

sti.triple

The target triple of the subtarget, as a string like tm.triple (use LLVM.Triple to interpret it).

sti.cpu

The name of the CPU. Targets may fill it in, e.g., X86 uses "generic" when no CPU is given.

sti.features

The feature string of the subtarget, e.g., "+avx2,-fma". Targets may extend the feature string that the subtarget was created with, e.g., X86 prepends the features that the triple implies, like +64bit-mode.

See also: LLVM.hasfeature, LLVM.hasfeatures, LLVM.processor_features.

dispose(sti::LLVM.SubtargetInfo)

Dispose of the given subtarget information, unless it belongs to a target machine.

LLVM.processor_features(sti::LLVM.SubtargetInfo) -> Vector{String}

Get the names of the features that the target of the subtarget knows about, sorted by name, like the keys of C++'s MCSubtargetInfo::getAllProcessorFeatures(). These are the names that LLVM.hasfeature and LLVM.hasfeatures accept.

LLVM.hasfeature(sti::LLVM.SubtargetInfo, name::AbstractString)

Check whether the subtarget has the feature of the given name (e.g., "avx2", without a + or - flag) enabled, including when it is enabled because another feature implies it. Throws an ArgumentError if the target doesn't have a feature of that name (see LLVM.processor_features).

LLVM.hasfeatures(sti::LLVM.SubtargetInfo, flags::AbstractString)

Check whether the subtarget matches all flags of a comma-separated feature string, e.g., "+avx2,-fma": whether it has every feature that is flagged with + enabled, and every feature flagged with - disabled. This is C++'s MCSubtargetInfo::checkFeatures as of LLVM 21, which checks every flag by itself, on every version of LLVM. Earlier versions of checkFeatures also checked the features that a flagged feature implies, and ignored unknown features, while later versions abort on them.

Throws an ArgumentError if a flag doesn't start with + or -, or names a feature that the target doesn't have (see LLVM.processor_features). Empty flags are ignored, so an empty string matches every subtarget.

DataLayout

A parsed version of the target data layout string in and methods for querying it.

The target data layout string is specified by the target - a frontend generating LLVM IR is required to generate the right target data for the target being codegen'd to.

Properties

dl.byteorder

The byte order of the data layout, LLVM.ByteOrdering.Big or LLVM.ByteOrdering.Little.

dl.globals_addrspace

The address space used for global variables by the data layout.

dispose(dl::DataLayout)

Dispose of the given target data layout.

pointersize(dl::DataLayout, [addrspace::Integer])

Get the size of pointers in the given address space (0 by default) for the target data layout, in bytes.

intptr(dl::DataLayout, [addrspace::Integer])

Get the integer type that is the same size as a pointer for the target data layout.

bit_size(dl::DataLayout, typ::LLVMType)

Get the size of the given type in bits for the target data layout, like C++'s DataLayout::getTypeSizeInBits, e.g., 1 for i1.

See also: storage_size, abi_size.

storage_size(dl::DataLayout, typ::LLVMType)

Get the number of bytes that storing a value of the given type may overwrite, for the target data layout, like C++'s DataLayout::getTypeStoreSize, e.g., 1 for i1 and 2 for i9.

abi_size(dl::DataLayout, typ::LLVMType)

Get the offset in bytes between successive values of the given type in memory, including alignment padding, for the target data layout, like C++'s DataLayout::getTypeAllocSize.

abi_alignment(dl::DataLayout, typ::LLVMType)

Get the ABI alignment of the given type in bytes for the target data layout.

frame_alignment(dl::DataLayout, typ::LLVMType)

Get the call frame alignment of the given type in bytes for the target data layout.

preferred_alignment(dl::DataLayout, typ::LLVMType)
preferred_alignment(dl::DataLayout, var::GlobalVariable)

Get the preferred alignment of the given type or global variable in bytes for the target data layout.

element_at(dl::DataLayout, typ::StructType, offset::Integer)

Get the index of the element of a struct type that contains the given byte offset, for the target data layout. Like the elements of the struct type, elements are numbered from 1.

See also: offsetof.

offsetof(dl::DataLayout, typ::StructType, i::Integer)

Get the byte offset of the ith element of a struct type, for the target data layout. Like the elements of the struct type, elements are numbered from 1.

See also: element_at.

LLVM.constant_offset(gep, dl::DataLayout)

Compute the offset in bytes that a getelementptr instruction or constant expression adds to its pointer operand, according to the data layout dl, or nothing if the offset isn't constant. The offset is a signed integer, computed with the index width of the pointer's address space, and returned as a BigInt.

Only GEPs that compute a single pointer are supported, not those that compute a vector of pointers.

LLVM.constant_offset(T::Type{<:Integer}, gep, dl::DataLayout)

Compute the offset like LLVM.constant_offset(gep, dl), but return it as an integer of type T (e.g., Int), throwing an InexactError if it doesn't fit.

LLVM.strip_and_accumulate_constant_offsets(ptr::Value, dl::DataLayout;
                                           allow_non_inbounds=false)

Strip the constant offsets from the pointer ptr: getelementptr instructions and constant expressions with constant indices, as well as casts that don't change the address, like LLVM's Value::stripAndAccumulateConstantOffsets. Returns the base pointer and the accumulated offset in bytes, as a BigInt, which is computed as a signed integer of the index width of the pointer's address space. If nothing can be stripped, the result is (ptr, 0).

By default, only inbounds GEPs are stripped. With allow_non_inbounds=true, other GEPs are stripped as well, in which case the offset does not imply that the pointer is within the bounds of the object the base points to.

LLVM.strip_and_accumulate_constant_offsets(T::Type{<:Integer}, ptr, dl; kwargs...)

Strip the offsets in the same way, but return the offset as an integer of type T (e.g., Int), throwing an InexactError if it doesn't fit.

Disassembler

A disassembler for machine code of a specific target, which decodes raw bytes into textual assembly instructions.

See also: disassemble.

dispose(dis::Disassembler)

Dispose of the given disassembler.

disassemble(dis::Disassembler, code::AbstractVector{UInt8}; address::Integer=0)

Disassemble the machine code in code, returning a lazy iterator of instructions. The address keyword specifies where the first byte of code resides in the target's address space, which is used to compute the address of every instruction.

Each instruction is a named tuple with fields:

• address::UInt64: the address of the instruction;
• size::Int: the number of bytes the instruction occupies;
• text::Union{String,Nothing}: the textual representation of the instruction, or nothing if the bytes could not be decoded. In that case, size is 1 and disassembly resumes at the next byte, which may not be an instruction boundary on targets with fixed-width instructions.

The iterator borrows the disassembler, so it must be consumed before the disassembler is disposed of. The disassembler must not be used by multiple tasks concurrently.

Examples

Disassembler("x86_64-linux-gnu") do dis
    for (; address, text) in disassemble(dis, code; address=0x1000)
        println(string(address; base=16), ": ", something(text, "<invalid>"))
    end
end

disassemble(io::IO, dis::Disassembler, code::AbstractVector{UInt8}; address::Integer=0)

Disassemble the machine code in code, and print the instructions to io, one per line. Bytes that could not be decoded are printed as .byte directives.