Data.LLVM.IR.Core

Core LLVM IR data types and utility functions.

This module defines the fundamental data types for representing LLVM IR constructs,
including linkage types, calling conventions, visibility modifiers, and basic value types.
It also provides utility functions for name escaping and type manipulation.

Definitions

unescape : String -> String

  Escape all special characters in a string.
  
  Applies `unescapeC` to every character in the input string and concatenates
  the results. This ensures the entire string is safe for use as an LLVM identifier.
  
  @ s The string to escape
  Returns the escaped string with all special characters replaced

Visibility: public export

data Linkage : Type

  Linkage types that specify how symbols are linked and their visibility.
  
  LLVM linkage determines symbol resolution, optimization opportunities,
  and visibility across module boundaries. Maps directly to LLVM IR linkage types.
  
  Examples:
  - `Private`: Symbol not visible outside the module
  - `Internal`: Symbol has internal linkage (like C static)
  - `External`: Symbol can be linked from other modules
  - `Weak`: Symbol can be replaced by another definition

Totality: total
Visibility: public export
Constructors:

Private : Linkage

  Symbol not visible outside this module

Internal : Linkage

  Symbol has internal linkage (like C static)

Available : Linkage

  Available externally for inspection but not linking

LinkOnce : Linkage

  Link once semantics - can be replaced

Weak : Linkage

  Weak linkage - can be replaced by non-weak definitions

Common : Linkage

  Common linkage (for uninitialized globals)

Appending : Linkage

  Appending linkage (for arrays like llvm.global_ctors)

ExternWeak : Linkage

  External weak linkage

LinkOnceODR : Linkage

  Link once ODR (One Definition Rule) semantics

WeakODR : Linkage

  Weak ODR linkage

External : Linkage

  External linkage (default)

Hint: 

Encode ATM Linkage VString

data CallingConvention : Type

  Calling conventions that specify parameter passing and register usage.
  
  LLVM calling conventions determine how function parameters are passed,
  which registers are used, and other ABI details. Different conventions
  provide different performance characteristics and compatibility.
  
  Examples:
  - `C`: Standard C calling convention
  - `Fast`: Optimized for performance
  - `Cold`: Optimized for infrequently called functions

Totality: total
Visibility: public export
Constructors:

C : CallingConvention

  Standard C calling convention (default)

Fast : CallingConvention

  Fast calling convention for performance

Cold : CallingConvention

  Cold calling convention for rarely-called functions

GHC : CallingConvention

  Glasgow Haskell Compiler calling convention

CC11 : CallingConvention

  High Performance Erlang calling convention

AnyReg : CallingConvention

  Any register calling convention

PreserveMost : CallingConvention

  Preserve most registers calling convention

PreserveAll : CallingConvention

  Preserve all registers calling convention

PreserveNone : CallingConvention

  Preserve no registers calling convention

CxxFastTL : CallingConvention

  C++ fast thread-local calling convention

Tail : CallingConvention

  Tail calling convention

Swift : CallingConvention

  Swift calling convention

SwiftTail : CallingConvention

  Swift tail calling convention

CFGuardCheck : CallingConvention

  Control Flow Guard check calling convention

CustomCC : Int -> CallingConvention

  Custom calling convention with numeric ID

Hint: 

Encode ATM CallingConvention VString

data Visibility : Type

  Symbol visibility modifiers for controlling external visibility.
  
  Visibility attributes control how symbols are exposed when linking
  shared libraries and executables. They correspond to ELF visibility
  attributes and similar concepts on other platforms.

Totality: total
Visibility: public export
Constructors:

Default : Visibility

  Default visibility (symbol is externally visible)

Hidden : Visibility

  Hidden visibility (symbol not visible outside shared object)

Protected : Visibility

  Protected visibility (symbol visible but not preemptible)

Hint: 

Encode ATM Visibility VString

data DLLStorage : Type

  DLL storage class specifiers for Windows targets.
  
  These attributes specify import/export behavior for symbols
  when targeting Windows DLL files.

Totality: total
Visibility: public export
Constructors:

DLLExport : DLLStorage

  Symbol is exported from this DLL

DLLImport : DLLStorage

  Symbol is imported from another DLL

Hint: 

Encode ATM DLLStorage VString

data ThreadLocality : Type

  Thread-local storage models for thread-local variables.
  
  These specify different implementation strategies for thread-local storage,
  each with different performance and dynamic loading characteristics.

Totality: total
Visibility: public export
Constructors:

LocalDynamic : ThreadLocality

  Local dynamic TLS model

InitialExec : ThreadLocality

  Initial exec TLS model

LocalExec : ThreadLocality

  Local exec TLS model

Hint: 

Encode ATM ThreadLocality VString

data Preemption : Type

  Preemption specifiers for symbol resolution.
  
  Controls whether symbols can be preempted (replaced) by other
  definitions at link or load time.

Totality: total
Visibility: public export
Constructors:

Preemptible : Preemption

  Symbol can be preempted by other definitions

NonPreemptible : Preemption

  Symbol cannot be preempted (dso_local)

Hint: 

Encode ATM Preemption VString

data AddressInfo : Type

  Address significance information for symbols.
  
  Indicates whether the address of a symbol is significant for
  program semantics, affecting optimization opportunities.

Totality: total
Visibility: public export
Constructors:

UnnamedGlobal : AddressInfo

  Global symbol address is not significant (unnamed_addr)

UnnamedLocal : AddressInfo

  Local symbol address is not significant (local_unnamed_addr)

Hint: 

Encode ATM AddressInfo VString

data AddressSpace : Type

  Address space specifications for memory layout.
  
  LLVM supports multiple address spaces to model different types of memory
  (e.g., global vs. local memory in GPU architectures).

Totality: total
Visibility: public export
Constructors:

NamedSpace : String -> AddressSpace

  Named address space

UnnamedSpace : Int -> AddressSpace

  Numbered address space  

Hint: 

Encode ATM AddressSpace VString

data Name : Type

  LLVM identifier types for different kinds of names.
  
  LLVM uses different prefixes to distinguish between different types
  of identifiers in the IR. Each name type has a specific purpose and
  namespace within LLVM.

Totality: total
Visibility: public export
Constructors:

Local : String -> Name

  Local variable or register name (prefixed with %)

Global : String -> Name

  Global variable or function name (prefixed with @)

Special : String -> Name

  Special compiler-generated name (prefixed with $)

MetadataN : String -> Name

  Metadata node name (prefixed with !)

AttributeN : String -> Name

  Attribute group name (prefixed with #)

LabelN : String -> Name

  Basic block label name (suffixed with :)

IntrinsicN : String -> Name

  LLVM intrinsic function name (starts with "@llvm.")

CustomN : String -> Name

  User-defined custom name type

Trash : Name

  Trash register, for operations that don't assign

Hints:

Encode ATM Name VString

LBlock (Maybe Name -> List LStatement)

Walk Name LExpr

data LTypeF : Type

  Floating-point type formats supported by LLVM.
  
  These correspond to different floating-point representations
  with varying precision and range characteristics.

Totality: total
Visibility: public export
Constructors:

Half : LTypeF

  IEEE 754 half precision (16-bit)

Bfloat : LTypeF

  Brain floating point (16-bit)

LFloat : LTypeF

  IEEE 754 single precision (32-bit)

LDouble : LTypeF

  IEEE 754 double precision (64-bit)

FP128 : LTypeF

  IEEE 754 quadruple precision (128-bit)

X86_FP80 : LTypeF

  x86 extended precision (80-bit)

PPC_FP128 : LTypeF

  PowerPC double-double (128-bit)

Hint: 

Encode ATM LTypeF VString

data LType : Type

  LLVM type representation.
  
  Represents all possible LLVM IR types including primitives,
  aggregates, functions, and target-specific types.

Totality: total
Visibility: public export
Constructors:

LPtr : LType

  Generic pointer type (opaque pointer)

LPtrTo : LType -> LType

  Pointer type to something (depreacted)

LPtrToAddr : AddressSpace -> LType -> LType

  Pointer to type in address space (depractated)

LPtrAddr : AddressSpace -> LType

  Pointer in specific address space

LVoid : LType

  Void type (no value)

LFun : LType -> List LType -> LType

  Function type with fixed arguments

LFunVarArg : LType -> List LType -> LType -> LType

  Variadic function type with fixed and variable arguments

LOpaque : LType

  Opaque type (structure not defined)

LInt : Int -> LType

  Integer type with specified bit width

LFloating : LTypeF -> LType

  Floating-point type

LX86_AMX : LType

  x86 Advanced Matrix Extensions type

LVector : Int -> LType -> LType

  Fixed-size vector type

LVectorScale : Int -> LType -> LType

  Scalable vector type (size determined at runtime)

LLabel : LType

  Label type for basic block references

LToken : LType

  Token type for representing state

LArray : Int -> LType -> LType

  Array type with fixed size and element type

LStruct : List LType -> LType

  Structure type with named fields

LPackedStruct : List LType -> LType

  Packed structure type (no padding)

LMetadata : LType

  Metadata type

Hints:

Encode ATM LType VString

Walk LType FunctionArgSpec

Walk (UnaryOpcode, (LType, LExpr)) LOperation

Walk (BinaryOpcode, (LType, (LExpr, LExpr))) LOperation

Walk (ConversionOpCode, (LType, (LExpr, LType))) LOperation

record WithType : Type -> Type

  Wrapper for values with explicit type information.
  
  Many LLVM IR constructs require both a value and its type.
  This record provides a convenient way to pair them together.
  
  @ a The type of the value being wrapped

Totality: total
Visibility: public export
Constructor: 

MkWithType : LType -> a -> WithType a

Projections:

.tpe : WithType a -> LType

  The LLVM type of this value

.value : WithType a -> a

  The actual value

Hint: 

Encode ATM a VString => Encode ATM (WithType a) VString

.tpe : WithType a -> LType

  The LLVM type of this value

Visibility: public export

tpe : WithType a -> LType

  The LLVM type of this value

Visibility: public export

.value : WithType a -> a

  The actual value

Visibility: public export

value : WithType a -> a

  The actual value

Visibility: public export

data Attribute : Type

  Function and parameter attributes in LLVM IR.
  
  Attributes provide additional information about function parameters,
  return values, and function behavior to enable optimizations and
  specify ABI details.

Totality: total
Visibility: public export
Constructors:

ZeroExt : Attribute

  Zero extend parameter/return value

SignExt : Attribute

  Sign extend parameter/return value

NoExt : Attribute

  No extension (target-specific behavior)

ByVal : LType -> Attribute

  Pass by value with specified type

ByRef : LType -> Attribute

  Pass by reference with specified type

Preallocated : LType -> Attribute

  Preallocated memory with specified type

Inalloca : LType -> Attribute

  In-alloca parameter with specified type

SRet : LType -> Attribute

  Structure return with specified type

Align : Nat -> Attribute

  Alignment requirement in bytes

NoAlias : Attribute

  No aliasing with other pointers

NoFree : Attribute

  Memory is never freed

Nest : Attribute

  Nested function parameter

Returned : Attribute

  Return value of function

NoNull : Attribute

  Pointer is never null

Dereferenceable : Nat -> Attribute

  Pointer dereferenceable for N bytes

DereferenceableOrNull : Nat -> Attribute

  Pointer dereferenceable for N bytes or null

SwiftSelf : Attribute

  Swift self parameter

SwiftAsync : Attribute

  Swift async parameter

SwiftError : Attribute

  Swift error parameter

ImmArg : Attribute

  Immediate argument (must be constant)

NoUndef : Attribute

  Value is not undefined (not undef or poison)

AlignStack : Nat -> Attribute

  Stack alignment requirement

AllocAlign : Attribute

  Allocation alignment parameter

AllocPtr : Attribute

  Allocation pointer result

ReadNone : Attribute

  Function/parameter doesn't read memory

ReadOnly : Attribute

  Function/parameter only reads memory

WriteOnly : Attribute

  Function/parameter only writes memory

Writeable : Attribute

  Memory pointed to is writable

DeadOnUnwind : Attribute

  Value is dead on exception unwind

DeadOnReturn : Attribute

  Value is dead on function return

OtherAttribute : String -> Attribute

Hint: 

Encode ATM Attribute VString

record FunctionArgSpec : Type

  Function argument specification with type and attributes.
  
  Represents a single function parameter including its type,
  any associated attributes, and optional name.

Totality: total
Visibility: public export
Constructor: 

MkFunctionArgSpec : LType -> List Attribute -> Maybe String -> FunctionArgSpec

Projections:

.attrs : FunctionArgSpec -> List Attribute

  Attributes applied to this parameter

.name : FunctionArgSpec -> Maybe String

  Optional parameter name for documentation

.type : FunctionArgSpec -> LType

  The type of this parameter

Hints:

Encode ATM FunctionArgSpec VString

Walk LType FunctionArgSpec

.type : FunctionArgSpec -> LType

  The type of this parameter

Visibility: public export

type : FunctionArgSpec -> LType

  The type of this parameter

Visibility: public export

.attrs : FunctionArgSpec -> List Attribute

  Attributes applied to this parameter

Visibility: public export

attrs : FunctionArgSpec -> List Attribute

  Attributes applied to this parameter

Visibility: public export

.name : FunctionArgSpec -> Maybe String

  Optional parameter name for documentation

Visibility: public export

name : FunctionArgSpec -> Maybe String

  Optional parameter name for documentation

Visibility: public export

data Assembly : Type

  Inline assembly representation.
  
  Allows embedding target-specific assembly code directly in LLVM IR.
  Currently supports only basic inline assembly without constraints.

Totality: total
Visibility: public export
Constructor: 

BasicAsm : String -> Assembly

  Basic inline assembly with assembly string

data Metadata : Type

  LLVM metadata representation.
  
  Metadata provides additional information that doesn't affect program
  semantics but can be used by debuggers, profilers, and other tools.

Totality: total
Visibility: public export
Constructors:

MetadataTuple : List Metadata -> Metadata

  A metadata tuple containing multiple metadata elements

MetadataNamed : String -> Metadata

  Named metadata

MetadataString : String -> Metadata

MetadataValue : WithType LExpr -> Metadata

MetadataCustom : String -> Metadata

Hint: 

Encode ATM Metadata VString

data LExpr : Type

Totality: total
Visibility: public export
Constructors:

LInt : Int -> LExpr

  Integer constant value

LFloat : String -> LExpr

  Floating-point constant (as string to preserve precision)

LBool : Bool -> LExpr

  Boolean constant (true/false)

LNull : LExpr

  Null pointer constant

LToken : LExpr

  Token constant for state tracking

LString : String -> LExpr

  String literal constant

LArray : List (WithType LExpr) -> LExpr

  Array constant with typed elements

LVector : List (WithType LExpr) -> LExpr

  Vector constant with typed elements

LStruct : List (WithType LExpr) -> LExpr

  Structure constant with typed fields

LUndefined : LExpr

  Undefined value (undefined behavior if used)

LPoison : LExpr

  Poison value (more undefined than undefined)

LZero : LExpr

  Zero initializer for any type

LMetadata : Metadata -> LExpr

  Metadata constant

LPtr : Name -> LExpr

  Pointer to named global/function

LVar : Name -> LExpr

Hints:

Encode ATM LExpr VString

Walk Int LExpr

Walk String LExpr

Walk Bool LExpr

Walk Name LExpr

Walk (UnaryOpcode, (LType, LExpr)) LOperation

Walk (BinaryOpcode, (LType, (LExpr, LExpr))) LOperation

Walk (ConversionOpCode, (LType, (LExpr, LType))) LOperation

=DEPRECATED=

LConstE : LExpr -> LExpr

Visibility: public export

data LTag : Type

  Custom metadata tags for LLVM constructs.
  
  Tags provide a way to attach custom metadata to various LLVM IR elements
  for tooling, debugging, or custom optimization passes.

Totality: total
Visibility: public export
Constructor: 

CTag : String -> LTag

  A custom named tag

Hint: 

Encode ATM LTag VString

record SymbolInfo : Type

  Symbol information record for global symbols.
  
  Collects various symbol properties that affect linking, visibility,
  and optimization behavior. Used for both global variables and functions.

Totality: total
Visibility: public export
Constructor: 

MkSymbolInfo : Maybe Linkage -> Maybe Preemption -> Maybe Visibility -> Maybe DLLStorage -> SymbolInfo

Projections:

.dllStorage : SymbolInfo -> Maybe DLLStorage

  DLL storage class (Windows-specific)

.linkage : SymbolInfo -> Maybe Linkage

  Symbol linkage type

.preemption : SymbolInfo -> Maybe Preemption

  Symbol preemption specification

.visibility : SymbolInfo -> Maybe Visibility

  Symbol visibility

Hint: 

Encode ATM SymbolInfo VString

.linkage : SymbolInfo -> Maybe Linkage

  Symbol linkage type

Visibility: public export

linkage : SymbolInfo -> Maybe Linkage

  Symbol linkage type

Visibility: public export

.preemption : SymbolInfo -> Maybe Preemption

  Symbol preemption specification

Visibility: public export

preemption : SymbolInfo -> Maybe Preemption

  Symbol preemption specification

Visibility: public export

.visibility : SymbolInfo -> Maybe Visibility

  Symbol visibility

Visibility: public export

visibility : SymbolInfo -> Maybe Visibility

  Symbol visibility

Visibility: public export

.dllStorage : SymbolInfo -> Maybe DLLStorage

  DLL storage class (Windows-specific)

Visibility: public export

dllStorage : SymbolInfo -> Maybe DLLStorage

  DLL storage class (Windows-specific)

Visibility: public export

Label : Type

  Type alias for basic block labels.
  
  Labels are represented as expressions for flexibility in referencing
  different types of basic block identifiers.

Visibility: public export

data FastMathFlag : Type

  Fast math optimization flags for floating-point operations.
  
  These flags enable various floating-point optimizations by relaxing
  strict IEEE 754 compliance in exchange for improved performance.

Totality: total
Visibility: public export
Constructors:

FFast : FastMathFlag

  Enable all fast math optimizations

NoNaNs : FastMathFlag

  Assume no NaN values exist

NoInfs : FastMathFlag

  Assume no infinite values exist

NoSignedZeros : FastMathFlag

  Assume signed zeros can be ignored

Hint: 

Encode ATM FastMathFlag VString

FastMath : Type

  Collection of fast math flags.
  
  A list of fast math flags that can be applied to floating-point
  operations to enable various optimizations.

Visibility: public export