Well-Formedness¶

It is important to note that this document describes ‘well formed’ LLVMassembly language. There is a difference between what the parser acceptsand what is considered ‘well formed’. For example, the followinginstruction is syntactically okay, but not well formed:

%x=addi321,%x

because the definition of%x does not dominate all of its uses. TheLLVM infrastructure provides a verification pass that may be used toverify that an LLVM module is well formed. This pass is automaticallyrun by the parser after parsing input assembly and by the optimizerbefore it outputs bitcode. The violations pointed out by the verifierpass indicate bugs in transformation passes or input to the parser.

Identifiers¶

LLVM identifiers come in two basic types: global and local. Globalidentifiers (functions, global variables) begin with the'@'character. Local identifiers (register names, types) begin with the'%' character. Additionally, there are three different formats foridentifiers, for different purposes:

1. Named values are represented as a string of characters with theirprefix. For example,%foo,@DivisionByZero,%a.really.long.identifier. The actual regular expression used is‘[%@][-a-zA-Z$._][-a-zA-Z$._0-9]*’. Identifiers that require othercharacters in their names can be surrounded with quotes. Specialcharacters may be escaped using"\xx" wherexx is the ASCIIcode for the character in hexadecimal. In this way, any character canbe used in a name value, even quotes themselves. The"\01" prefixcan be used on global values to suppress mangling.

2. Unnamed values are represented as an unsigned numeric value withtheir prefix. For example,%12,@2,%44.

3. Constants, which are described in the sectionConstants below.

LLVM requires that values start with a prefix for two reasons: Compilersdon’t need to worry about name clashes with reserved words, and the setof reserved words may be expanded in the future without penalty.Additionally, unnamed identifiers allow a compiler to quickly come upwith a temporary variable without having to avoid symbol tableconflicts.

Reserved words in LLVM are very similar to reserved words in otherlanguages. There are keywords for different opcodes (’add’,‘bitcast’, ‘ret’, etc…), for primitive type names (’void’,‘i32’, etc…), and others. These reserved words cannot conflictwith variable names, because none of them start with a prefix character('%' or'@').

Here is an example of LLVM code to multiply the integer variable‘%X’ by 8:

The easy way:

%result=muli32%X,8

After strength reduction:

%result=shli32%X,3

And the hard way:

%0=addi32%X,%X; yields i32:%0%1=addi32%0,%0/*yieldsi32:%1*/%result=addi32%1,%1

This last way of multiplying%X by 8 illustrates several importantlexical features of LLVM:

1. Comments are delimited with a ‘;’ and go until the end of line.Alternatively, comments can start with/* and terminate with*/.

2. Unnamed temporaries are created when the result of a computation isnot assigned to a named value.

3. By default, unnamed temporaries are numbered sequentially (using aper-function incrementing counter, starting with 0). However, when explicitlyspecifying temporary numbers, it is allowed to skip over numbers.

   Note that basic blocks and unnamed function parameters are included in thisnumbering. For example, if the entry basic block is not given a label nameand all function parameters are named, then it will get number 0.

It also shows a convention that we follow in this document. Whendemonstrating instructions, we will follow an instruction with a commentthat defines the type and name of value produced.

String constants¶

Strings in LLVM programs are delimited by" characters. Within astring, all bytes are treated literally with the exception of\characters, which start escapes, and the first" character, whichends the string.

There are two kinds of escapes.

• \\ represents a single\ character.

• \ followed by two hexadecimal characters (0-9, a-f, or A-F)represents the byte with the given value (e.g.\00 represents anull byte).

To represent a" character, use\22. (\" will end the stringwith a trailing\.)

Newlines do not terminate string constants; strings can span multiplelines.

The interpretation of string constants (e.g. their character encoding)depends on context.

Module Structure¶

LLVM programs are composed ofModule’s, each of which is atranslation unit of the input programs. Each module consists offunctions, global variables, and symbol table entries. Modules may becombined together with the LLVM linker, which merges function (andglobal variable) definitions, resolves forward declarations, and mergessymbol table entries. Here is an example of the “hello world” module:

; Declare the string constant as a global constant.@.str=privateunnamed_addrconstant[13xi8]c"hello world\0A\00"; External declaration of the puts functiondeclarei32@puts(ptrcaptures(none))nounwind; Definition of main functiondefinei32@main(){; Call puts function to write out the string to stdout.calli32@puts(ptr@.str)reti320}; Named metadata!0=!{i3242,null,!"string"}!foo=!{!0}

This example is made up of aglobal variable named“.str”, an external declaration of the “puts” function, afunction definition for “main” andnamed metadata “foo”.

In general, a module is made up of a list of global values (where bothfunctions and global variables are global values). Global values arerepresented by a pointer to a memory location (in this case, a pointerto an array of char, and a pointer to a function), and have one of thefollowinglinkage types.

Linkage Types¶

All Global Variables and Functions have one of the following types oflinkage:

private

Global values with “private” linkage are only directlyaccessible by objects in the current module. In particular, linkingcode into a module with a private global value may cause theprivate to be renamed as necessary to avoid collisions. Because thesymbol is private to the module, all references can be updated. Thisdoesn’t show up in any symbol table in the object file.

internal

Similar to private, but the value shows as a local symbol(STB_LOCAL in the case of ELF) in the object file. Thiscorresponds to the notion of the ‘static’ keyword in C.

available_externally

Globals with “available_externally” linkage are never emitted intothe object file corresponding to the LLVM module. From the linker’sperspective, anavailable_externally global is equivalent toan external declaration. They exist to allow inlining and otheroptimizations to take place given knowledge of the definition of theglobal, which is known to be somewhere outside the module. Globalswithavailable_externally linkage are allowed to be discarded atwill, and allow inlining and other optimizations. This linkage type isonly allowed on definitions, not declarations.

linkonce

Globals with “linkonce” linkage are merged with other globals ofthe same name when linkage occurs. This can be used to implementsome forms of inline functions, templates, or other code which mustbe generated in each translation unit that uses it, but where thebody may be overridden with a more definitive definition later.Unreferencedlinkonce globals are allowed to be discarded. Notethatlinkonce linkage does not actually allow the optimizer toinline the body of this function into callers because it doesn’tknow if this definition of the function is the definitive definitionwithin the program or whether it will be overridden by a strongerdefinition. To enable inlining and other optimizations, use“linkonce_odr” linkage.

weak

“weak” linkage has the same merging semantics aslinkoncelinkage, except that unreferenced globals withweak linkage maynot be discarded. This is used for globals that are declared “weak”in C source code.

common

“common” linkage is most similar to “weak” linkage, but theyare used for tentative definitions in C, such as “intX;” atglobal scope. Symbols with “common” linkage are merged in thesame way asweaksymbols, and they may not be deleted ifunreferenced.common symbols may not have an explicit section,must have a zero initializer, and may not be marked‘constant’. Functions and aliases may not havecommon linkage.

appending

“appending” linkage may only be applied to global variables ofpointer to array type. When two global variables with appendinglinkage are linked together, the two global arrays are appendedtogether. This is the LLVM, typesafe, equivalent of having thesystem linker append together “sections” with identical names when.o files are linked.

Unfortunately this doesn’t correspond to any feature in .o files, so itcan only be used for variables likellvm.global_ctors which llvminterprets specially.

extern_weak

The semantics of this linkage follow the ELF object file model: thesymbol is weak until linked, if not linked, the symbol becomes nullinstead of being an undefined reference.

linkonce_odr,weak_odr

Theodr suffix indicates that all globals defined with the given nameare equivalent, along the lines of the C++ “one definition rule” (“ODR”).Informally, this means we can inline functions and fold loads of constants.

Formally, use the following definition: when anodr function iscalled, one of the definitions is non-deterministically chosen to run. Forodr variables, if any byte in the value is not equal in allinitializers, that byte is apoison value. Foraliases and ifuncs, apply the rule for the underlying function or variable.

These linkage types are otherwise the same as their non-odr versions.

external

If none of the above identifiers are used, the global is externallyvisible, meaning that it participates in linkage and can be used toresolve external symbol references.

It is illegal for a global variable or functiondeclaration to have anylinkage type other thanexternal orextern_weak.

Calling Conventions¶

LLVMfunctions,calls andinvokes can all have an optional calling conventionspecified for the call. The calling convention of any pair of dynamiccaller/callee must match, or the behavior of the program is undefined.The following calling conventions are supported by LLVM, and more may beadded in the future:

“ccc” - The C calling convention

This calling convention (the default if no other calling conventionis specified) matches the target C calling conventions. This callingconvention supports varargs function calls and tolerates somemismatch in the declared prototype and implemented declaration ofthe function (as does normal C).

“fastcc” - The fast calling convention

This calling convention attempts to make calls as fast as possible(e.g. by passing things in registers). This calling conventionallows the target to use whatever tricks it wants to produce fastcode for the target, without having to conform to an externallyspecified ABI (Application Binary Interface).Tail calls can onlybe optimized when this, the tailcc, the GHC or the HiPE convention isused. This callingconvention does not support varargs and requires the prototype of allcallees to exactly match the prototype of the function definition.

“coldcc” - The cold calling convention

This calling convention attempts to make code in the caller asefficient as possible under the assumption that the call is notcommonly executed. As such, these calls often preserve all registersso that the call does not break any live ranges in the caller side.This calling convention does not support varargs and requires theprototype of all callees to exactly match the prototype of thefunction definition. Furthermore the inliner doesn’t consider such functioncalls for inlining.

“ghccc” - GHC convention

This calling convention has been implemented specifically for use bytheGlasgow Haskell Compiler (GHC).It passes everything in registers, going to extremes to achieve thisby disabling callee save registers. This calling convention shouldnot be used lightly but only for specific situations such as analternative to theregister pinning performance technique oftenused when implementing functional programming languages. At themoment only X86, AArch64, and RISCV support this convention. Thefollowing limitations exist:

• OnX86-32 only up to 4 bit type parameters are supported. Nofloating-point types are supported.

• OnX86-64 only up to 10 bit type parameters and 6floating-point parameters are supported.

• OnAArch64 only up to 4 32-bit floating-point parameters,4 64-bit floating-point parameters, and 10 bit type parametersare supported.

• RISCV64 only supports up to 11 bit type parameters, 432-bit floating-point parameters, and 4 64-bit floating-pointparameters.

This calling convention supportstail calloptimization but requiresboth the caller and callee are using it.

“cc11” - The HiPE calling convention

This calling convention has been implemented specifically for use bytheHigh-Performance Erlang(HiPE) compiler,thenative code compiler of theEricsson’s Open Source Erlang/OTPsystem. It uses moreregisters for argument passing than the ordinary C callingconvention and defines no callee-saved registers. The callingconvention properly supportstail calloptimization but requiresthat both the caller and the callee use it. It uses aregister pinningmechanism, similar to GHC’s convention, for keeping frequentlyaccessed runtime components pinned to specific hardware registers.At the moment only X86 supports this convention (both 32 and 64bit).

“anyregcc” - Dynamic calling convention for code patching

This is a special convention that supports patching an arbitrary codesequence in place of a call site. This convention forces the callarguments into registers but allows them to be dynamicallyallocated. This can currently only be used with calls tollvm.experimental.patchpoint because only this intrinsic recordsthe location of its arguments in a side table. SeeStack maps and patch points in LLVM.

“preserve_mostcc” - ThePreserveMost calling convention

This calling convention attempts to make the code in the caller asunintrusive as possible. This convention behaves identically to theCcalling convention on how arguments and return values are passed, but ituses a different set of caller/callee-saved registers. This alleviates theburden of saving and recovering a large register set before and after thecall in the caller. If the arguments are passed in callee-saved registers,then they will be preserved by the callee across the call. This doesn’tapply for values returned in callee-saved registers.

• On X86-64 the callee preserves all general purpose registers, except forR11 and return registers, if any. R11 can be used as a scratch register.The treatment of floating-point registers (XMMs/YMMs) matches the OS’s Ccalling convention: on most platforms, they are not preserved and need tobe saved by the caller, but on Windows, xmm6-xmm15 are preserved.

• On AArch64 the callee preserve all general purpose registers, exceptX0-X8 and X16-X18. Not allowed withnest.

The idea behind this convention is to support calls to runtime functionsthat have a hot path and a cold path. The hot path is usually a small pieceof code that doesn’t use many registers. The cold path might need to call out toanother function and therefore only needs to preserve the caller-savedregisters, which haven’t already been saved by the caller. ThePreserveMost calling convention is very similar to thecold callingconvention in terms of caller/callee-saved registers, but they are used fordifferent types of function calls.coldcc is for function calls that arerarely executed, whereaspreserve_mostcc function calls are intended to beon the hot path and definitely executed a lot. Furthermorepreserve_mostccdoesn’t prevent the inliner from inlining the function call.

This calling convention will be used by a future version of the ObjectiveCruntime and should therefore still be considered experimental at this time.Although this convention was created to optimize certain runtime calls tothe ObjectiveC runtime, it is not limited to this runtime and might be usedby other runtimes in the future too. The current implementation onlysupports X86-64, but the intention is to support more architectures in thefuture.

“preserve_allcc” - ThePreserveAll calling convention

This calling convention attempts to make the code in the caller even lessintrusive than thePreserveMost calling convention. This callingconvention also behaves identical to theC calling convention on howarguments and return values are passed, but it uses a different set ofcaller/callee-saved registers. This removes the burden of saving andrecovering a large register set before and after the call in the caller. Ifthe arguments are passed in callee-saved registers, then they will bepreserved by the callee across the call. This doesn’t apply for valuesreturned in callee-saved registers.

• On X86-64 the callee preserves all general purpose registers, except forR11. R11 can be used as a scratch register. Furthermore it also preservesall floating-point registers (XMMs/YMMs).

• On AArch64 the callee preserve all general purpose registers, exceptX0-X8 and X16-X18. Furthermore it also preserves lower 128 bits of V8-V31SIMD floating point registers. Not allowed withnest.

The idea behind this convention is to support calls to runtime functionsthat don’t need to call out to any other functions.

This calling convention, like thePreserveMost calling convention, will beused by a future version of the ObjectiveC runtime and should be consideredexperimental at this time.

“preserve_nonecc” - ThePreserveNone calling convention

This calling convention doesn’t preserve any general registers. So allgeneral registers are caller saved registers. It also uses all generalregisters to pass arguments. This attribute doesn’t impact non-generalpurpose registers (e.g. floating point registers, on X86 XMMs/YMMs).Non-general purpose registers still follow the standard c callingconvention. Currently it is for x86_64 and AArch64 only.

“cxx_fast_tlscc” - TheCXX_FAST_TLS calling convention for access functions

Clang generates an access function to access C++-style Thread Local Storage(TLS). The access function generally has an entry block, an exit block and aninitialization block that is run at the first time. The entry and exit blockscan access a few TLS IR variables, each access will be lowered to aplatform-specific sequence.

This calling convention aims to minimize overhead in the caller bypreserving as many registers as possible (all the registers that arepreserved on the fast path, composed of the entry and exit blocks).

This calling convention behaves identical to theC calling convention onhow arguments and return values are passed, but it uses a different set ofcaller/callee-saved registers.

Given that each platform has its own lowering sequence, hence its own setof preserved registers, we can’t use the existingPreserveMost.

• On X86-64 the callee preserves all general purpose registers, except forRDI and RAX.

“tailcc” - Tail callable calling convention

This calling convention ensures that calls in tail position will always betail call optimized. This calling convention is equivalent to fastcc,except for an additional guarantee that tail calls will be producedwhenever possible.Tail calls can only be optimized when this, the fastcc,the GHC or the HiPE convention is used.This calling convention does not support varargs and requires the prototype ofall callees to exactly match the prototype of the function definition.

“swiftcc” - This calling convention is used for Swift language.

• On X86-64 RCX and R8 are available for additional integer returns, andXMM2 and XMM3 are available for additional FP/vector returns.

• On iOS platforms, we use AAPCS-VFP calling convention.

“swifttailcc”

This calling convention is likeswiftcc in most respects, but also thecallee pops the argument area of the stack so that mandatory tail calls arepossible as intailcc.

“cfguard_checkcc” - Windows Control Flow Guard (Check mechanism)

This calling convention is used for the Control Flow Guard check function,calls to which can be inserted before indirect calls to check that the calltarget is a valid function address. The check function has no return value,but it will trigger an OS-level error if the address is not a valid target.The set of registers preserved by the check function, and the registercontaining the target address are architecture-specific.

• On X86 the target address is passed in ECX.

• On ARM the target address is passed in R0.

• On AArch64 the target address is passed in X15.

“cc<n>” - Numbered convention

Any calling convention may be specified by number, allowingtarget-specific calling conventions to be used. Target specificcalling conventions start at 64.

More calling conventions can be added/defined on an as-needed basis, tosupport Pascal conventions or any other well-known target-independentconvention.

Visibility Styles¶

All Global Variables and Functions have one of the following visibilitystyles:

“default” - Default style

On targets that use the ELF object file format, default visibilitymeans that the declaration is visible to other modules and, inshared libraries, means that the declared entity may be overridden.On Darwin, default visibility means that the declaration is visibleto other modules. On XCOFF, default visibility means no explicitvisibility bit will be set and whether the symbol is visible(i.e “exported”) to other modules depends primarily on export listsprovided to the linker. Default visibility corresponds to “externallinkage” in the language.

“hidden” - Hidden style

Two declarations of an object with hidden visibility refer to thesame object if they are in the same shared object. Usually, hiddenvisibility indicates that the symbol will not be placed into thedynamic symbol table, so no other module (executable or sharedlibrary) can reference it directly.

“protected” - Protected style

On ELF, protected visibility indicates that the symbol will beplaced in the dynamic symbol table, but that references within thedefining module will bind to the local symbol. That is, the symbolcannot be overridden by another module.

A symbol withinternal orprivate linkage must havedefaultvisibility.

DLL Storage Classes¶

All Global Variables, Functions and Aliases can have one of the followingDLL storage class:

dllimport

“dllimport” causes the compiler to reference a function or variable viaa global pointer to a pointer that is set up by the DLL exporting thesymbol. On Microsoft Windows targets, the pointer name is formed bycombining__imp_ and the function or variable name.

dllexport

On Microsoft Windows targets, “dllexport” causes the compiler to providea global pointer to a pointer in a DLL, so that it can be referenced with thedllimport attribute. the pointer name is formed by combining__imp_and the function or variable name. On XCOFF targets,dllexport indicatesthat the symbol will be made visible to other modules using “exported”visibility and thus placed by the linker in the loader section symbol table.Since this storage class exists for defining a dll interface, the compiler,assembler and linker know it is externally referenced and must refrain fromdeleting the symbol.

A symbol withinternal orprivate linkage cannot have a DLL storageclass.

Thread Local Storage Models¶

A variable may be defined asthread_local, which means that it willnot be shared by threads (each thread will have a separated copy of thevariable). Not all targets support thread-local variables. Optionally, aTLS model may be specified:

localdynamic

For variables that are only used within the current shared library.

initialexec

For variables in modules that will not be loaded dynamically.

localexec

For variables defined in the executable and only used within it.

If no explicit model is given, the “general dynamic” model is used.

The models correspond to the ELF TLS models; seeELF Handling ForThread-Local Storage formore information on under which circumstances the different models maybe used. The target may choose a different TLS model if the specifiedmodel is not supported, or if a better choice of model can be made.

A model can also be specified in an alias, but then it only governs howthe alias is accessed. It will not have any effect in the aliasee.

For platforms without linker support of ELF TLS model, the -femulated-tlsflag can be used to generate GCC compatible emulated TLS code.

Runtime Preemption Specifiers¶

Global variables, functions and aliases may have an optional runtime preemptionspecifier. If a preemption specifier isn’t given explicitly, then asymbol is assumed to bedso_preemptable.

dso_preemptable

Indicates that the function or variable may be replaced by a symbol fromoutside the linkage unit at runtime.

dso_local

The compiler may assume that a function or variable marked asdso_localwill resolve to a symbol within the same linkage unit. Direct access willbe generated even if the definition is not within this compilation unit.

Structure Types¶

LLVM IR allows you to specify both “identified” and “literal”structuretypes. Literal types are uniqued structurally, but identified typesare never uniqued. Anopaque structural type can also be usedto forward declare a type that is not yet available.

An example of an identified structure specification is:

%mytype=type{%mytype*,i32}

Prior to the LLVM 3.0 release, identified types were structurally uniqued. Onlyliteral types are uniqued in recent versions of LLVM.

Non-Integral Pointer Type¶

Note: non-integral pointer types are a work in progress, and they should beconsidered experimental at this time.

LLVM IR optionally allows the frontend to denote pointers in certain addressspaces as “non-integral” via thedatalayout string.Non-integral pointer types represent pointers that have anunspecified bitwiserepresentation; that is, the integral representation may be target dependent orunstable (not backed by a fixed integer).

inttoptr andptrtoint instructions have the same semantics as forintegral (i.e. normal) pointers in that they convert integers to and fromcorresponding pointer types, but there are additional implications to beaware of. Because the bit-representation of a non-integral pointer maynot be stable, two identical casts of the same operand may or may notreturn the same value. Said differently, the conversion to or from thenon-integral type depends on environmental state in an implementationdefined manner.

If the frontend wishes to observe aparticular value following a cast, thegenerated IR must fence with the underlying environment in an implementationdefined manner. (In practice, this tends to requirenoinline routines forsuch operations.)

From the perspective of the optimizer,inttoptr andptrtoint fornon-integral types are analogous to ones on integral types with onekey exception: the optimizer may not, in general, insert new dynamicoccurrences of such casts. If a new cast is inserted, the optimizer wouldneed to either ensure that a) all possible values are valid, or b)appropriate fencing is inserted. Since the appropriate fencing isimplementation defined, the optimizer can’t do the latter. The former ischallenging as many commonly expected properties, such asptrtoint(v)-ptrtoint(v)==0, don’t hold for non-integral types.Similar restrictions apply to intrinsics that might examine the pointer bits,such asllvm.ptrmask.

The alignment information provided by the frontend for a non-integral pointer(typically using attributes or metadata) must be valid for every possiblerepresentation of the pointer.

Global Variables¶

Global variables define regions of memory allocated at compilation timeinstead of run-time.

Global variable definitions must be initialized with a sized value.

Global variables in other translation units can also be declared, in whichcase they don’t have an initializer.

Global variables can optionally specify alinkage type.

Either global variable definitions or declarations may have an explicit sectionto be placed in and may have an optional explicit alignment specified. If thereis a mismatch between the explicit or inferred section information for thevariable declaration and its definition the resulting behavior is undefined.

A variable may be defined as a globalconstant, which indicates thatthe contents of the variable willnever be modified (enabling betteroptimization, allowing the global data to be placed in the read-onlysection of an executable, etc). Note that variables that need runtimeinitialization cannot be markedconstant as there is a store to thevariable.

LLVM explicitly allowsdeclarations of global variables to be markedconstant, even if the final definition of the global is not. Thiscapability can be used to enable slightly better optimization of theprogram, but requires the language definition to guarantee thatoptimizations based on the ‘constantness’ are valid for the translationunits that do not include the definition.

As SSA values, global variables define pointer values that are in scopefor (i.e. they dominate) all basic blocks in the program. Global variablesalways define a pointer to their “content” type because they describe aregion of memory, and allallocated object in LLVM areaccessed through pointers.

Global variables can be marked withunnamed_addr which indicatesthat the address is not significant, only the content. Constants markedlike this can be merged with other constants if they have the sameinitializer. Note that a constant with significant addresscan bemerged with aunnamed_addr constant, the result being a constantwhose address is significant.

If thelocal_unnamed_addr attribute is given, the address is known tonot be significant within the module.

A global variable may be declared to reside in a target-specificnumbered address space. For targets that support them, address spacesmay affect how optimizations are performed and/or what targetinstructions are used to access the variable. The default address spaceis zero. The address space qualifier must precede any other attributes.

LLVM allows an explicit section to be specified for globals. If thetarget supports it, it will emit globals to the section specified.Additionally, the global can placed in a comdat if the target has the necessarysupport.

External declarations may have an explicit section specified. Sectioninformation is retained in LLVM IR for targets that make use of thisinformation. Attaching section information to an external declaration is anassertion that its definition is located in the specified section. If thedefinition is located in a different section, the behavior is undefined.

LLVM allows an explicit code model to be specified for globals. If thetarget supports it, it will emit globals in the code model specified,overriding the code model used to compile the translation unit.The allowed values are “tiny”, “small”, “kernel”, “medium”, “large”.This may be extended in the future to specify global data layout thatdoesn’t cleanly fit into a specific code model.

By default, global initializers are optimized by assuming that globalvariables defined within the module are not modified from theirinitial values before the start of the global initializer. This istrue even for variables potentially accessible from outside themodule, including those with external linkage or appearing in@llvm.used or dllexported variables. This assumption may be suppressedby marking the variable withexternally_initialized.

An explicit alignment may be specified for a global, which must be apower of 2. If not present, or if the alignment is set to zero, thealignment of the global is set by the target to whatever it feelsconvenient. If an explicit alignment is specified, the global is forcedto have exactly that alignment. Targets and optimizers are not allowedto over-align the global if the global has an assigned section. In thiscase, the extra alignment could be observable: for example, code couldassume that the globals are densely packed in their section and try toiterate over them as an array, alignment padding would break thisiteration. For TLS variables, the module flagMaxTLSAlign, if present,limits the alignment to the given value. Optimizers are not allowed toimpose a stronger alignment on these variables. The maximum alignmentis1<<32.

For global variable declarations, as well as definitions that may bereplaced at link time (linkonce,weak,extern_weak andcommonlinkage types), the allocation size and alignment of the definition it resolvesto must be greater than or equal to that of the declaration or replaceabledefinition, otherwise the behavior is undefined.

Globals can also have aDLL storage class,an optionalruntime preemption specifier,an optionalglobal attributes andan optional list of attachedmetadata.

Variables and aliases can have aThread Local Storage Model.

Globals cannot be or containScalable vectors because theirsize is unknown at compile time. They are allowed in structs to facilitateintrinsics returning multiple values. Generally, structs containing scalablevectors are not considered “sized” and cannot be used in loads, stores, allocas,or GEPs. The only exception to this rule is for structs that contain scalablevectors of the same type (e.g.{<vscalex2xi32>,<vscalex2xi32>}contains the same type while{<vscalex2xi32>,<vscalex2xi64>}doesn’t). These kinds of structs (we may call them homogeneous scalable vectorstructs) are considered sized and can be used in loads, stores, allocas, butnot GEPs.

Globals withtoc-data attribute set are stored in TOC of XCOFF. Theiralignments are not larger than that of a TOC entry. Optimizations should notincrease their alignments to mitigate TOC overflow.

Syntax:

@<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility]                   [DLLStorageClass] [ThreadLocal]                   [(unnamed_addr|local_unnamed_addr)] [AddrSpace]                   [ExternallyInitialized]                   <global | constant> <Type> [<InitializerConstant>]                   [, section "name"] [, partition "name"]                   [, comdat [($name)]] [, align <Alignment>]                   [, code_model "model"]                   [, no_sanitize_address] [, no_sanitize_hwaddress]                   [, sanitize_address_dyninit] [, sanitize_memtag]                   (, !name !N)*

For example, the following defines a global in a numbered address spacewith an initializer, section, and alignment:

@G=addrspace(5)constantfloat1.0,section"foo",align4

The following example just declares a global variable

@G=externalglobali32

The following example defines a global variable with thelarge code model:

@G=internalglobali320,code_model"large"

The following example defines a thread-local global with theinitialexec TLS model:

@G=thread_local(initialexec)globali320,align4

Functions¶

LLVM function definitions consist of the “define” keyword, anoptionallinkage type, an optionalruntime preemptionspecifier, an optionalvisibilitystyle, an optionalDLL storage class,an optionalcalling convention,an optionalunnamed_addr attribute, a return type, an optionalparameter attribute for the return type, a functionname, a (possibly empty) argument list (each with optionalparameterattributes), optionalfunction attributes,an optional address space, an optional section, an optional partition,an optional alignment, an optionalcomdat,an optionalgarbage collector name, an optionalprefix,an optionalprologue,an optionalpersonality,an optional list of attachedmetadata,an opening curly brace, a list of basic blocks, and a closing curly brace.

Syntax:

define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass]       [cconv] [ret attrs]       <ResultType> @<FunctionName> ([argument list])       [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs]       [section "name"] [partition "name"] [comdat [($name)]] [align N]       [gc] [prefix Constant] [prologue Constant] [personality Constant]       (!name !N)* { ... }

The argument list is a comma separated sequence of arguments where eachargument is of the following form:

Syntax:

<type>[parameterAttrs][name]

LLVM function declarations consist of the “declare” keyword, anoptionallinkage type, an optionalvisibility style, an optionalDLL storage class, anoptionalcalling convention, an optionalunnamed_addrorlocal_unnamed_addr attribute, an optional address space, a return type,an optionalparameter attribute for the return type, a function name, a possiblyempty list of arguments, an optional alignment, an optionalgarbagecollector name, an optionalprefix, and an optionalprologue.

Syntax:

declare[linkage][visibility][DLLStorageClass][cconv][retattrs]<ResultType>@<FunctionName>([argumentlist])[(unnamed_addr|local_unnamed_addr)][alignN][gc][prefixConstant][prologueConstant]

A function definition contains a list of basic blocks, forming the CFG (ControlFlow Graph) for the function. Each basic block may optionally start with a label(giving the basic block a symbol table entry), contains a list of instructionsanddebug records,and ends with aterminator instruction (such as a branch orfunction return). If an explicit label name is not provided, a block is assignedan implicit numbered label, using the next value from the same counter as usedfor unnamed temporaries (see above). For example, if afunction entry block does not have an explicit label, it will be assigned label“%0”, then the first unnamed temporary in that block will be “%1”, etc. If anumeric label is explicitly specified, it must match the numeric label thatwould be used implicitly.

The first basic block in a function is special in two ways: it isimmediately executed on entrance to the function, and it is not allowedto have predecessor basic blocks (i.e. there can not be any branches tothe entry block of a function). Because the block can have nopredecessors, it also cannot have anyPHI nodes.

LLVM allows an explicit section to be specified for functions. If thetarget supports it, it will emit functions to the section specified.Additionally, the function can be placed in a COMDAT.

An explicit alignment may be specified for a function. If not present,or if the alignment is set to zero, the alignment of the function is setby the target to whatever it feels convenient. If an explicit alignmentis specified, the function is forced to have at least that muchalignment. All alignments must be a power of 2.

If theunnamed_addr attribute is given, the address is known to notbe significant and two identical functions can be merged.

If thelocal_unnamed_addr attribute is given, the address is known tonot be significant within the module.

If an explicit address space is not given, it will default to the programaddress space from thedatalayout string.

Aliases¶

Aliases, unlike function or variables, don’t create any new data. Theyare just a new symbol and metadata for an existing position.

Aliases have a name and an aliasee that is either a global value or aconstant expression.

Aliases may have an optionallinkage type, an optionalruntime preemption specifier, an optionalvisibility style, an optionalDLL storage class and an optionaltls model.

Syntax:

@<Name>=[Linkage][PreemptionSpecifier][Visibility][DLLStorageClass][ThreadLocal][(unnamed_addr|local_unnamed_addr)]alias<AliaseeTy>,<AliaseeTy>*@<Aliasee>[,partition"name"]

The linkage must be one ofprivate,internal,linkonce,weak,linkonce_odr,weak_odr,external,available_externally. Notethat some system linkers might not correctly handle dropping a weak symbol thatis aliased.

Aliases that are notunnamed_addr are guaranteed to have the same address asthe aliasee expression.unnamed_addr ones are only guaranteed to pointto the same content.

If thelocal_unnamed_addr attribute is given, the address is known tonot be significant within the module.

Since aliases are only a second name, some restrictions apply, of whichsome can only be checked when producing an object file:

• The expression defining the aliasee must be computable at assemblytime. Since it is just a name, no relocations can be used.

• No alias in the expression can be weak as the possibility of theintermediate alias being overridden cannot be represented in anobject file.

• If the alias has theavailable_externally linkage, the aliasee must be anavailable_externally global value; otherwise the aliasee can be anexpression but no global value in the expression can be a declaration, sincethat would require a relocation, which is not possible.

• If either the alias or the aliasee may be replaced by a symbol outside themodule at link time or runtime, any optimization cannot replace the alias withthe aliasee, since the behavior may be different. The alias may be used as aname guaranteed to point to the content in the current module.

IFuncs¶

IFuncs, like as aliases, don’t create any new data or func. They are just a newsymbol that is resolved at runtime by calling a resolver function.

On ELF platforms, IFuncs are resolved by the dynamic linker at load time. OnMach-O platforms, they are lowered in terms of.symbol_resolver functions,which lazily resolve the callee the first time they are called.

IFunc may have an optionallinkage type and an optionalvisibility style.

Syntax:

@<Name>=[Linkage][PreemptionSpecifier][Visibility]ifunc<IFuncTy>,<ResolverTy>*@<Resolver>[,partition"name"]

Comdats¶

Comdat IR provides access to object file COMDAT/section group functionalitywhich represents interrelated sections.

Comdats have a name which represents the COMDAT key and a selection kind toprovide input on how the linker deduplicates comdats with the same key in twodifferent object files. A comdat must be included or omitted as a unit.Discarding the whole comdat is allowed but discarding a subset is not.

A global object may be a member of at most one comdat. Aliases are placed in thesame COMDAT that their aliasee computes to, if any.

Syntax:

$<Name> = comdat SelectionKind

For selection kinds other thannodeduplicate, only one of the duplicatecomdats may be retained by the linker and the members of the remaining comdatsmust be discarded. The following selection kinds are supported:

any

The linker may choose any COMDAT key, the choice is arbitrary.

exactmatch

The linker may choose any COMDAT key but the sections must contain thesame data.

largest

The linker will choose the section containing the largest COMDAT key.

nodeduplicate

No deduplication is performed.

samesize

The linker may choose any COMDAT key but the sections must contain thesame amount of data.

• XCOFF and Mach-O don’t support COMDATs.

• COFF supports all selection kinds. Non-nodeduplicate selection kinds needa non-local linkage COMDAT symbol.

• ELF supportsany andnodeduplicate.

• WebAssembly only supportsany.

Here is an example of a COFF COMDAT where a function will only be selected ifthe COMDAT key’s section is the largest:

$foo = comdat largest@foo = global i32 2, comdat($foo)define void @bar() comdat($foo) {  ret void}

In a COFF object file, this will create a COMDAT section with selection kindIMAGE_COMDAT_SELECT_LARGEST containing the contents of the@foo symboland another COMDAT section with selection kindIMAGE_COMDAT_SELECT_ASSOCIATIVE which is associated with the first COMDATsection and contains the contents of the@bar symbol.

As a syntactic sugar the$name can be omitted if the name is the same asthe global name:

$foo=comdatany@foo=globali322,comdat@bar=globali323,comdat($foo)

There are some restrictions on the properties of the global object.It, or an alias to it, must have the same name as the COMDAT group whentargeting COFF.The contents and size of this object may be used during link-time to determinewhich COMDAT groups get selected depending on the selection kind.Because the name of the object must match the name of the COMDAT group, thelinkage of the global object must not be local; local symbols can get renamedif a collision occurs in the symbol table.

The combined use of COMDATS and section attributes may yield surprising results.For example:

$foo=comdatany$bar=comdatany@g1=globali3242,section"sec",comdat($foo)@g2=globali3242,section"sec",comdat($bar)

From the object file perspective, this requires the creation of two sectionswith the same name. This is necessary because both globals belong to differentCOMDAT groups and COMDATs, at the object file level, are represented bysections.

Note that certain IR constructs like global variables and functions maycreate COMDATs in the object file in addition to any which are specified usingCOMDAT IR. This arises when the code generator is configured to emit globalsin individual sections (e.g. when-data-sections or-function-sectionsis supplied tollc).

Named Metadata¶

Named metadata is a collection of metadata.Metadatanodes (but not metadata strings) are the only validoperands for a named metadata.

1. Named metadata are represented as a string of characters with themetadata prefix. The rules for metadata names are the same as foridentifiers, but quoted names are not allowed."\xx" type escapesare still valid, which allows any character to be part of a name.

Syntax:

; Some unnamed metadata nodes, which are referenced by the named metadata.!0 = !{!"zero"}!1 = !{!"one"}!2 = !{!"two"}; A named metadata.!name = !{!0, !1, !2}

Parameter Attributes¶

The return type and each parameter of a function type may have a set ofparameter attributes associated with them. Parameter attributes areused to communicate additional information about the result orparameters of a function. Parameter attributes are considered to be partof the function, not of the function type, so functions with differentparameter attributes can have the same function type. Parameter attributes canbe placed both on function declarations/definitions, and at call-sites.

Parameter attributes are either simple keywords or strings that follow thespecified type. Multiple parameter attributes, when required, are separated byspaces. For example:

; On function declarations/definitions:declarei32@printf(ptrnoaliascaptures(none),...)declarei32@atoi(i8zeroext)declaresignexti8@returns_signed_char()definevoid@baz(i32"amdgpu-flat-work-group-size"="1,256"%x); On call-sites:calli32@atoi(i8zeroext%x)callsignexti8@returns_signed_char()

Note that any attributes for the function result (nonnull,signext) come before the result type.

Parameter attributes can be broadly separated into two kinds: ABI attributesthat affect how values are passed to/from functions, likezeroext,inreg,byval, orsret. And optimization attributes, which provideadditional optimization guarantees, likenoalias,nonnull anddereferenceable.

ABI attributes must be specifiedboth at the function declaration/definitionand call-site, otherwise the behavior may be undefined. ABI attributes cannotbe safely dropped. Optimization attributes do not have to match betweencall-site and function: The intersection of their implied semantics applies.Optimization attributes can also be freely dropped.

If an integer argument to a function is not marked signext/zeroext/noext, thekind of extension used is target-specific. Some targets depend forcorrectness on the kind of extension to be explicitly specified.

Currently, only the following parameter attributes are defined:

zeroext

This indicates to the code generator that the parameter or returnvalue should be zero-extended to the extent required by the target’sABI by the caller (for a parameter) or the callee (for a return value).

signext

This indicates to the code generator that the parameter or returnvalue should be sign-extended to the extent required by the target’sABI (which is usually 32-bits) by the caller (for a parameter) orthe callee (for a return value).

noext

This indicates to the code generator that the parameter or returnvalue has the high bits undefined, as for a struct in register, andtherefore does not need to be sign or zero extended. This is the sameas default behavior and is only actually used (by some targets) tovalidate that one of the attributes is always present.

inreg

This indicates that this parameter or return value should be treatedin a special target-dependent fashion while emitting code fora function call or return (usually, by putting it in a register asopposed to memory, though some targets use it to distinguish betweentwo different kinds of registers). Use of this attribute istarget-specific.

byval(<ty>)

This indicates that the pointer parameter should really be passed byvalue to the function. The attribute implies that a hidden copy ofthe pointee is made between the caller and the callee, so the calleeis unable to modify the value in the caller. This attribute is onlyvalid on LLVM pointer arguments. It is generally used to passstructs and arrays by value, but is also valid on pointers toscalars. The copy is considered to belong to the caller not thecallee (for example,readonly functions should not write tobyval parameters). This is not a valid attribute for returnvalues.

The byval type argument indicates the in-memory value type.

The byval attribute also supports specifying an alignment with thealign attribute. It indicates the alignment of the stack slot toform and the known alignment of the pointer specified to the callsite. If the alignment is not specified, then the code generatormakes a target-specific assumption.

byref(<ty>)

Thebyref argument attribute allows specifying the pointeememory type of an argument. This is similar tobyval, but doesnot imply a copy is made anywhere, or that the argument is passedon the stack. This implies the pointer is dereferenceable up tothe storage size of the type.

It is not generally permissible to introduce a write to anbyref pointer. The pointer may have any address space and maybe read only.

This is not a valid attribute for return values.

The alignment for anbyref parameter can be explicitlyspecified by combining it with thealign attribute, similar tobyval. If the alignment is not specified, then the code generatormakes a target-specific assumption.

This is intended for representing ABI constraints, and is notintended to be inferred for optimization use.

preallocated(<ty>)

This indicates that the pointer parameter should really be passed byvalue to the function, and that the pointer parameter’s pointee hasalready been initialized before the call instruction. This attributeis only valid on LLVM pointer arguments. The argument must be the valuereturned by the appropriatellvm.call.preallocated.arg on nonmusttail calls, or the corresponding caller parameter inmusttailcalls, although it is ignored during codegen.

A nonmusttail function call with apreallocated attribute inany parameter must have a"preallocated" operand bundle. Amusttailfunction call cannot have a"preallocated" operand bundle.

The preallocated attribute requires a type argument.

The preallocated attribute also supports specifying an alignment with thealign attribute. It indicates the alignment of the stack slot toform and the known alignment of the pointer specified to the callsite. If the alignment is not specified, then the code generatormakes a target-specific assumption.

inalloca(<ty>)

Theinalloca argument attribute allows the caller to take theaddress of outgoing stack arguments. Aninalloca argument mustbe a pointer to stack memory produced by analloca instruction.The alloca, or argument allocation, must also be tagged with theinalloca keyword. Only the last argument may have theinallocaattribute, and that argument is guaranteed to be passed in memory.

An argument allocation may be used by a call at most once becausethe call may deallocate it. Theinalloca attribute cannot beused in conjunction with other attributes that affect argumentstorage, likeinreg,nest,sret, orbyval. Theinalloca attribute also disables LLVM’s implicit lowering oflarge aggregate return values, which means that frontend authorsmust lower them withsret pointers.

When the call site is reached, the argument allocation must havebeen the most recent stack allocation that is still live, or thebehavior is undefined. It is possible to allocate additional stackspace after an argument allocation and before its call site, but itmust be cleared off withllvm.stackrestore.

The inalloca attribute requires a type argument.

SeeDesign and Usage of the InAlloca Attribute for more information on how to use thisattribute.

sret(<ty>)

This indicates that the pointer parameter specifies the address of astructure that is the return value of the function in the sourceprogram. This pointer must be guaranteed by the caller to be valid:loads and stores to the structure may be assumed by the callee notto trap and to be properly aligned.

The sret type argument specifies the in memory type.

A function that accepts ansret argument must returnvoid.A return value may not besret.

elementtype(<ty>)

Theelementtype argument attribute can be used to specify a pointerelement type in a way that is compatible withopaque pointers.

Theelementtype attribute by itself does not carry any specificsemantics. However, certain intrinsics may require this attribute to bepresent and assign it particular semantics. This will be documented onindividual intrinsics.

The attribute may only be applied to pointer typed arguments of intrinsiccalls. It cannot be applied to non-intrinsic calls, and cannot be appliedto parameters on function declarations. For non-opaque pointers, the typepassed toelementtype must match the pointer element type.

align<n> oralign(<n>)

This indicates that the pointer value or vector of pointers has thespecified alignment. If applied to a vector of pointers,all pointers(elements) have the specified alignment. If the pointer value does not havethe specified alignment,poison value is returned orpassed instead. Thealign attribute should be combined with thenoundef attribute to ensure a pointer is aligned, or otherwise thebehavior is undefined. Note thatalign1 has no effect on non-byval,non-preallocated arguments.

Note that this attribute has additional semantics when combined with thebyval orpreallocated attribute, which are documented there.

noalias

This indicates that memory locations accessed via pointer valuesbased on the argument or return value are not alsoaccessed, during the execution of the function, via pointer values notbased on the argument or return value. This guarantee only holds formemory locations that aremodified, by any means, during the execution ofthe function. If there are other accesses not based on the argument orreturn value, the behavior is undefined. The attribute on a return valuealso has additional semantics, as described below. Both the caller and thecallee share the responsibility of ensuring that these requirements aremet. For further details, please see the discussion of the NoAlias responseinalias analysis.

Note that this definition ofnoalias is intentionally similarto the definition ofrestrict in C99 for function arguments.

For function return values, C99’srestrict is not meaningful,while LLVM’snoalias is. Furthermore, the semantics of thenoaliasattribute on return values are stronger than the semantics of the attributewhen used on function arguments. On function return values, thenoaliasattribute indicates that the function acts like a system memory allocationfunction, returning a pointer to allocated storage disjoint from thestorage for any other object accessible to the caller.

captures(...)

This attributes restrict the ways in which the callee may capture thepointer. This is not a valid attribute for return values. This attributeapplies only to the particular copy of the pointer passed in this argument.

The arguments ofcaptures is a list of captured pointer components,which may benone, or a combination of:

• address: The integral address of the pointer.

• address_is_null (subset ofaddress): Whether the address is null.

• provenance: The ability to access the pointer for both read and writeafter the function returns.

• read_provenance (subset ofprovenance): The ability to access thepointer only for reads after the function returns.

Additionally, it is possible to specify that some components are onlycaptured in certain locations. Currently only the return value (ret)and other (default) locations are supported.

Thepointer capture section discusses these semanticsin more detail.

Some examples of how to use the attribute:

• captures(none): Pointer not captured.

• captures(address,provenance): Equivalent to omitting the attribute.

• captures(address): Address may be captured, but not provenance.

• captures(address_is_null): Only captures whether the address is null.

• captures(address,read_provenance): Both address and provenancecaptured, but only for read-only access.

• captures(ret:address,provenance): Pointer captured through returnvalue only.

• captures(address_is_null,ret:address,provenance): The whole pointeris captured through the return value, and additionally whether the pointeris null is captured in some other way.

nofree

This indicates that callee does not free the pointer argument. This is nota valid attribute for return values.

nest

This indicates that the pointer parameter can be excised using thetrampoline intrinsics. This is not a validattribute for return values and can only be applied to one parameter.

returned

This indicates that the function always returns the argument as its returnvalue. This is a hint to the optimizer and code generator used whengenerating the caller, allowing value propagation, tail call optimization,and omission of register saves and restores in some cases; it is notchecked or enforced when generating the callee. The parameter and thefunction return type must be valid operands for thebitcast instruction. This is not a valid attribute forreturn values and can only be applied to one parameter.

nonnull

This indicates that the parameter or return pointer is not null. Thisattribute may only be applied to pointer typed parameters. This is notchecked or enforced by LLVM; if the parameter or return pointer is null,poison value is returned or passed instead.Thenonnull attribute should be combined with thenoundef attributeto ensure a pointer is not null or otherwise the behavior is undefined.

dereferenceable(<n>)

This indicates that the parameter or return pointer is dereferenceable. Thisattribute may only be applied to pointer typed parameters. A pointer thatis dereferenceable can be loaded from speculatively without a risk oftrapping. The number of bytes known to be dereferenceable must be providedin parentheses. It is legal for the number of bytes to be less than thesize of the pointee type. Thenonnull attribute does not implydereferenceability (consider a pointer to one element past the end of anarray), howeverdereferenceable(<n>) does implynonnull inaddrspace(0) (which is the default address space), except if thenull_pointer_is_valid function attribute is present.n should be a positive number. The pointer should be well defined,otherwise it is undefined behavior. This meansdereferenceable(<n>)impliesnoundef. When used in an assume operand bundle, more restrictedsemantics apply. Seeassume operand bundles formore details.

dereferenceable_or_null(<n>)

This indicates that the parameter or return value isn’t bothnon-null and non-dereferenceable (up to<n> bytes) at the sametime. All non-null pointers tagged withdereferenceable_or_null(<n>) aredereferenceable(<n>).For address space 0dereferenceable_or_null(<n>) implies thata pointer is exactly one ofdereferenceable(<n>) ornull,and in other address spacesdereferenceable_or_null(<n>)implies that a pointer is at least one ofdereferenceable(<n>)ornull (i.e. it may be bothnull anddereferenceable(<n>)). This attribute may only be applied topointer typed parameters.

swiftself

This indicates that the parameter is the self/context parameter. This is nota valid attribute for return values and can only be applied to oneparameter.

swiftasync

This indicates that the parameter is the asynchronous context parameter andtriggers the creation of a target-specific extended frame record to storethis pointer. This is not a valid attribute for return values and can onlybe applied to one parameter.

swifterror

This attribute is motivated to model and optimize Swift error handling. Itcan be applied to a parameter with pointer to pointer type or apointer-sized alloca. At the call site, the actual argument that correspondsto aswifterror parameter has to come from aswifterror alloca ortheswifterror parameter of the caller. Aswifterror value (eitherthe parameter or the alloca) can only be loaded and stored from, or used asaswifterror argument. This is not a valid attribute for return valuesand can only be applied to one parameter.

These constraints allow the calling convention to optimize access toswifterror variables by associating them with a specific register atcall boundaries rather than placing them in memory. Since this does changethe calling convention, a function which uses theswifterror attributeon a parameter is not ABI-compatible with one which does not.

These constraints also allow LLVM to assume that aswifterror argumentdoes not alias any other memory visible within a function and that aswifterror alloca passed as an argument does not escape.

immarg

This indicates the parameter is required to be an immediatevalue. This must be a trivial immediate integer or floating-pointconstant. Undef or constant expressions are not valid. This isonly valid on intrinsic declarations and cannot be applied to acall site or arbitrary function.

noundef

This attribute applies to parameters and return values. If the valuerepresentation contains any undefined or poison bits, the behavior isundefined. Note that this does not refer to padding introduced by thetype’s storage representation.

If memory sanitizer is enabled,noundef becomes an ABI attribute andmust match between the call-site and the function definition.

nofpclass(<testmask>)

This attribute applies to parameters and return values withfloating-point and vector of floating-point types, as well assupported aggregates of such types(matching the supported types forfast-math flags).The test mask has the same format as the second argument to thellvm.is.fpclass, and indicates which classesof floating-point values are not permitted for the value. For examplea bitmask of 3 indicates the parameter may not be a NaN.

If the value is a floating-point class indicated by thenofpclass test mask, apoison value ispassed or returned instead.

     @llvm.is.fpclass(nofpclass(test_mask) %x, test_mask) => false     @llvm.is.fpclass(nofpclass(test_mask) %x, ~test_mask) => true     nofpclass(all) => poison

In textual IR, various string names are supported for readabilityand can be combined. For examplenofpclass(nanpinfnzero)evaluates to a mask of 547.

This does not depend on the floating-point environment. Forexample, a function parameter markednofpclass(zero) indicatesno zero inputs. If this is applied to an argument in a functionmarked with“denormal-fp-math”indicating zero treatment of input denormals, it does not imply thevalue cannot be a denormal value which would compare equal to 0.

alignstack(<n>)

This indicates the alignment that should be considered by the backend whenassigning this parameter or return value to a stack slot during callingconvention lowering. The enforcement of the specified alignment istarget-dependent, as target-specific calling convention rules may overridethis value. This attribute serves the purpose of carrying language specificalignment information that is not mapped to base types in the backend (forexample, over-alignment specification through language attributes).

allocalign

The function parameter marked with this attribute is the alignment in bytes of thenewly allocated block returned by this function. The returned value must either havethe specified alignment or be the null pointer. The return value MAY be more alignedthan the requested alignment, but not less aligned. Invalid (e.g. non-power-of-2)alignments are permitted for the allocalign parameter, so long as the returned pointeris null. This attribute may only be applied to integer parameters.

allocptr

The function parameter marked with this attribute is the pointerthat will be manipulated by the allocator. For a realloc-likefunction the pointer will be invalidated upon success (but thesame address may be returned), for a free-like function thepointer will always be invalidated.

readnone

This attribute indicates that the function does not dereference thatpointer argument, even though it may read or write the memory that thepointer points to if accessed through other pointers.

If a function reads from or writes to a readnone pointer argument, thebehavior is undefined.

readonly

This attribute indicates that the function does not write through thispointer argument, even though it may write to the memory that the pointerpoints to.

If a function writes to a readonly pointer argument, the behavior isundefined.

writeonly

This attribute indicates that the function may write to, but does not readthrough this pointer argument (even though it may read from the memory thatthe pointer points to).

This attribute is understood in the same way as thememory(write)attribute. That is, the pointer may still be read as long as the read isnot observable outside the function. See thememory documentation forprecise semantics.

writable

This attribute is only meaningful in conjunction withdereferenceable(N)or another attribute that implies the firstN bytes of the pointerargument are dereferenceable.

In that case, the attribute indicates that the firstN bytes will be(non-atomically) loaded and stored back on entry to the function.

This implies that it’s possible to introduce spurious stores on entry tothe function without introducing traps or data races. This does notnecessarily hold throughout the whole function, as the pointer may escapeto a different thread during the execution of the function. See also theatomic optimization guide

The “other attributes” that imply dereferenceability aredereferenceable_or_null (if the pointer is non-null) and thesret,byval,byref,inalloca,preallocated family ofattributes. Note that not all of these combinations are useful, e.g.byval arguments are known to be writable even without this attribute.

Thewritable attribute cannot be combined withreadnone,readonly or amemory attribute that does not containargmem:write.

initializes((Lo1,Hi1),...)

This attribute indicates that the function initializes the ranges of thepointer parameter’s memory[%p+LoN,%p+HiN). Colloquially, this meansthat all bytes in the specified range are written before the functionreturns, and not read prior to the initializing write. If the functionunwinds, the write may not happen.

Formally, this is specified in terms of an “initialized” shadow state forall bytes in the range, which is set to “not initialized” at function entry.If a memory access is performed through a pointer based on the argument,and an accessed byte has not been marked as “initialized” yet, then:

• If the byte is stored with a non-volatile, non-atomic write, mark it as“initialized”.

• If the byte is stored with a volatile or atomic write, the behavior isundefined.

• If the byte is loaded, return a poison value.

Additionally, if the function returns normally, write an undef value to allbytes that are part of the range and have not been marked as “initialized”.

This attribute only holds for the memory accessed via this pointerparameter. Other arbitrary accesses to the same memory via other pointersare allowed.

Thewritable ordereferenceable attribute do not imply theinitializes attribute. Theinitializes attribute does not implywriteonly sinceinitializes allows reading from the pointerafter writing.

This attribute is a list of constant ranges in ascending order with nooverlapping or consecutive list elements.LoN/HiN are 64-bit integers,and negative values are allowed in case the argument points partway intoan allocation. An empty list is not allowed.

On abyval argument,initializes refers to the given parts of thecallee copy being overwritten. Abyval callee can never initialize theoriginal caller memory passed to thebyval argument.

dead_on_unwind

At a high level, this attribute indicates that the pointer argument is deadif the call unwinds, in the sense that the caller will not depend on thecontents of the memory. Stores that would only be visible on the unwindpath can be elided.

More precisely, the behavior is as-if any memory written through thepointer during the execution of the function is overwritten with a poisonvalue on unwind. This includes memory written by the implicit write impliedby thewritable attribute. The caller is allowed to access the affectedmemory, but all loads that are not preceded by a store will return poison.

This attribute cannot be applied to return values.

dead_on_return

This attribute indicates that the memory pointed to by the argument is deadupon function return, both upon normal return and if the calls unwinds, meaningthat the caller will not depend on its contents. Stores that would be observableeither on the return path or on the unwind path may be elided.

Specifically, the behavior is as-if any memory written through the pointerduring the execution of the function is overwritten with a poison valueupon function return. The caller may access the memory, but any loadnot preceded by a store will return poison.

This attribute does not imply aliasing properties. For pointer arguments thatdo not alias other memory locations,noalias attribute may be used inconjunction. Conversely, this attribute always impliesdead_on_unwind.

This attribute cannot be applied to return values.

range(<ty><a>,<b>)

This attribute expresses the possible range of the parameter or return value.If the value is not in the specified range, it is converted to poison.The arguments passed torange have the following properties:

• The type must match the scalar type of the parameter or return value.

• The paira,b represents the range[a,b).

• Botha andb are constants.

• The range is allowed to wrap.

• The empty range is represented using0,0.

• Otherwise,a andb are not allowed to be equal.

This attribute may only be applied to parameters or return values with integeror vector of integer types.

For vector-typed parameters, the range is applied element-wise.

Garbage Collector Strategy Names¶

Each function may specify a garbage collector strategy name, which is simply astring:

definevoid@f()gc"name"{...}

The supported values ofname includes thosebuilt in to LLVM and any provided by loaded plugins. Specifying a GCstrategy will cause the compiler to alter its output in order to support thenamed garbage collection algorithm. Note that LLVM itself does not contain agarbage collector, this functionality is restricted to generating machine codewhich can interoperate with a collector provided externally.

Prefix Data¶

Prefix data is data associated with a function which the codegenerator will emit immediately before the function’s entrypoint.The purpose of this feature is to allow frontends to associatelanguage-specific runtime metadata with specific functions and make itavailable through the function pointer while still allowing thefunction pointer to be called.

To access the data for a given function, a program may bitcast thefunction pointer to a pointer to the constant’s type and dereferenceindex -1. This implies that the IR symbol points just past the end ofthe prefix data. For instance, take the example of a function annotatedwith a singlei32,

definevoid@f()prefixi32123{...}

The prefix data can be referenced as,

%a=getelementptrinboundsi32,ptr@f,i32-1%b=loadi32,ptr%a

Prefix data is laid out as if it were an initializer for a global variableof the prefix data’s type. The function will be placed such that thebeginning of the prefix data is aligned. This means that if the sizeof the prefix data is not a multiple of the alignment size, thefunction’s entrypoint will not be aligned. If alignment of thefunction’s entrypoint is desired, padding must be added to the prefixdata.

A function may have prefix data but no body. This has similar semanticsto theavailable_externally linkage in that the data may be used by theoptimizers but will not be emitted in the object file.

Prologue Data¶

Theprologue attribute allows arbitrary code (encoded as bytes) tobe inserted prior to the function body. This can be used for enablingfunction hot-patching and instrumentation.

To maintain the semantics of ordinary function calls, the prologue data musthave a particular format. Specifically, it must begin with a sequence ofbytes which decode to a sequence of machine instructions, valid for themodule’s target, which transfer control to the point immediately succeedingthe prologue data, without performing any other visible action. This allowsthe inliner and other passes to reason about the semantics of the functiondefinition without needing to reason about the prologue data. Obviously thismakes the format of the prologue data highly target dependent.

A trivial example of valid prologue data for the x86 architecture isi8144,which encodes thenop instruction:

define void @f() prologue i8 144 { ... }

Generally prologue data can be formed by encoding a relative branch instructionwhich skips the metadata, as in this example of valid prologue data for thex86_64 architecture, where the first two bytes encodejmp.+10:

%0 = type <{ i8, i8, ptr }>define void @f() prologue %0 <{ i8 235, i8 8, ptr @md}> { ... }

A function may have prologue data but no body. This has similar semanticsto theavailable_externally linkage in that the data may be used by theoptimizers but will not be emitted in the object file.

Personality Function¶

Thepersonality attribute permits functions to specify what functionto use for exception handling.

Attribute Groups¶

Attribute groups are groups of attributes that are referenced by objects withinthe IR. They are important for keeping.ll files readable, because a lot offunctions will use the same set of attributes. In the degenerative case of a.ll file that corresponds to a single.c file, the single attributegroup will capture the important command line flags used to build that file.

An attribute group is a module-level object. To use an attribute group, anobject references the attribute group’s ID (e.g.#37). An object may referto more than one attribute group. In that situation, the attributes from thedifferent groups are merged.

Here is an example of attribute groups for a function that should always beinlined, has a stack alignment of 4, and which shouldn’t use SSE instructions:

; Target-independent attributes:attributes#0={alwaysinlinealignstack=4}; Target-dependent attributes:attributes#1={"no-sse"}; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".definevoid@f()#0#1{...}

Function Attributes¶

Function attributes are set to communicate additional information abouta function. Function attributes are considered to be part of thefunction, not of the function type, so functions with different functionattributes can have the same function type.

Function attributes are simple keywords or strings that follow the specifiedtype. Multiple attributes, when required, are separated by spaces.For example:

definevoid@f()noinline{...}definevoid@f()alwaysinline{...}definevoid@f()alwaysinlineoptsize{...}definevoid@f()optsize{...}definevoid@f()"no-sse"{...}

alignstack(<n>)

This attribute indicates that, when emitting the prologue andepilogue, the backend should forcibly align the stack pointer.Specify the desired alignment, which must be a power of two, inparentheses.

"alloc-family"="FAMILY"

This indicates which “family” an allocator function is part of. To avoidcollisions, the family name should match the mangled name of the primaryallocator function, that is “malloc” for malloc/calloc/realloc/free,“_Znwm” for::operator::new and::operator::delete, and“_ZnwmSt11align_val_t” for aligned::operator::new and::operator::delete. Matching malloc/realloc/free calls within a familycan be optimized, but mismatched ones will be left alone.

allockind("KIND")

Describes the behavior of an allocation function. The KIND string contains commaseparated entries from the following options:

• “alloc”: the function returns a new block of memory or null.

• “realloc”: the function returns a new block of memory or null. If theresult is non-null the memory contents from the start of the block up tothe smaller of the original allocation size and the new allocation sizewill match that of theallocptr argument and theallocptrargument is invalidated, even if the function returns the same address.

• “free”: the function frees the block of memory specified byallocptr.Functions marked as “free”allockind must return void.

• “uninitialized”: Any newly-allocated memory (either a new block froma “alloc” function or the enlarged capacity from a “realloc” function)will be uninitialized.

• “zeroed”: Any newly-allocated memory (either a new block from a “alloc”function or the enlarged capacity from a “realloc” function) will bezeroed.

• “aligned”: the function returns memory aligned according to theallocalign parameter.

The first three options are mutually exclusive, and the remaining optionsdescribe more details of how the function behaves. The remaining optionsare invalid for “free”-type functions.

"alloc-variant-zeroed"="FUNCTION"

This attribute indicates that another function is equivalent to an allocator function,but returns zeroed memory. The function must have “zeroed” allocation behavior,the samealloc-family, and take exactly the same arguments.

allocsize(<EltSizeParam>[,<NumEltsParam>])

This attribute indicates that the annotated function will always return atleast a given number of bytes (or null). Its arguments are zero-indexedparameter numbers; if one argument is provided, then it’s assumed that atleastCallSite.Args[EltSizeParam] bytes will be available at thereturned pointer. If two are provided, then it’s assumed thatCallSite.Args[EltSizeParam]*CallSite.Args[NumEltsParam] bytes areavailable. The referenced parameters must be integer types. No assumptionsare made about the contents of the returned block of memory.

alwaysinline

This attribute indicates that the inliner should attempt to inlinethis function into callers whenever possible, ignoring any activeinlining size threshold for this caller.

builtin

This indicates that the callee function at a call site should berecognized as a built-in function, even though the function’s declarationuses thenobuiltin attribute. This is only valid at call sites fordirect calls to functions that are declared with thenobuiltinattribute.

cold

This attribute indicates that this function is rarely called. Whencomputing edge weights, basic blocks post-dominated by a coldfunction call are also considered to be cold; and, thus, given lowweight.

convergent

This attribute indicates that this function is convergent.When it appears on a call/invoke, the convergent attributeindicates that we should treat the call as though we’re calling aconvergent function. This is particularly useful on indirectcalls; without this we may treat such calls as though the targetis non-convergent.

SeeConvergent Operation Semantics for further details.

It is an error to callllvm.experimental.convergence.entry from a function thatdoes not have this attribute.

disable_sanitizer_instrumentation

When instrumenting code with sanitizers, it can be important to skip certainfunctions to ensure no instrumentation is applied to them.

This attribute is not always similar to absentsanitize_<name>attributes: depending on the specific sanitizer, code can be inserted intofunctions regardless of thesanitize_<name> attribute to prevent falsepositive reports.

disable_sanitizer_instrumentation disables all kinds of instrumentation,taking precedence over thesanitize_<name> attributes and other compilerflags.

"dontcall-error"

This attribute denotes that an error diagnostic should be emitted when acall of a function with this attribute is not eliminated via optimization.Front ends can provide optionalsrcloc metadata nodes on call sites ofsuch callees to attach information about where in the source language such acall came from. A string value can be provided as a note.

"dontcall-warn"

This attribute denotes that a warning diagnostic should be emitted when acall of a function with this attribute is not eliminated via optimization.Front ends can provide optionalsrcloc metadata nodes on call sites ofsuch callees to attach information about where in the source language such acall came from. A string value can be provided as a note.

fn_ret_thunk_extern

This attribute tells the code generator that returns from functions shouldbe replaced with jumps to externally-defined architecture-specific symbols.For X86, this symbol’s identifier is__x86_return_thunk.

"frame-pointer"

This attribute tells the code generator whether the functionshould keep the frame pointer. The code generator may emit the frame pointereven if this attribute says the frame pointer can be eliminated.The allowed string values are:

• "none" (default) - the frame pointer can be eliminated, and it’sregister can be used for other purposes.

• "reserved" - the frame pointer register must either be updated topoint to a valid frame record for the current function, or not bemodified.

• "non-leaf" - the frame pointer should be kept if the function callsother functions.

• "all" - the frame pointer should be kept.

hot

This attribute indicates that this function is a hot spot of the programexecution. The function will be optimized more aggressively and will beplaced into special subsection of the text section to improving locality.

When profile feedback is enabled, this attribute has the precedence overthe profile information. By marking a functionhot, users can workaround the cases where the training input does not have good coverageon all the hot functions.

inlinehint

This attribute indicates that the source code contained a hint thatinlining this function is desirable (such as the “inline” keyword inC/C++). It is just a hint; it imposes no requirements on theinliner.

jumptable

This attribute indicates that the function should be added to ajump-instruction table at code-generation time, and that all address-takenreferences to this function should be replaced with a reference to theappropriate jump-instruction-table function pointer. Note that this createsa new pointer for the original function, which means that code that dependson function-pointer identity can break. So, any function annotated withjumptable must also beunnamed_addr.

memory(...)

This attribute specifies the possible memory effects of the call-site orfunction. It allows specifying the possible access kinds (none,read,write, orreadwrite) for the possible memory locationkinds (argmem,inaccessiblemem,errnomem, as well as a default).It is best understood by example:

• memory(none): Does not access any memory.

• memory(read): May read (but not write) any memory.

• memory(write): May write (but not read) any memory.

• memory(readwrite): May read or write any memory.

• memory(argmem:read): May only read argument memory.

• memory(argmem:read,inaccessiblemem:write): May only read argumentmemory and only write inaccessible memory.

• memory(argmem:read,errnomem:write): May only read argument memoryand only write errno.

• memory(read,argmem:readwrite): May read any memory (default mode)and additionally write argument memory.

• memory(readwrite,argmem:none): May access any memory apart fromargument memory.

The supported access kinds are:

• readwrite: Any kind of access to the location is allowed.

• read: The location is only read. Writing to the location is immediateundefined behavior. This includes the case where the location is read fromand then the same value is written back.

• write: Only writes to the location are observable outside the functioncall. However, the function may still internally read the location afterwriting it, as this is not observable. Reading the location prior towriting it results in a poison value.

• none: No reads or writes to the location are observed outside thefunction. It is always valid to read and write allocas, and to read globalconstants, even ifmemory(none) is used, as these effects are notexternally observable.

The supported memory location kinds are:

• argmem: This refers to accesses that are based on pointer argumentsto the function.

• inaccessiblemem: This refers to accesses to memory which is notaccessible by the current module (before return from the function – anallocator function may return newly accessible memory while onlyaccessing inaccessible memory itself). Inaccessible memory is often usedto model control dependencies of intrinsics.

• errnomem: This refers to accesses to theerrno variable.

• The default access kind (specified without a location prefix) applies toall locations that haven’t been specified explicitly, including those thatdon’t currently have a dedicated location kind (e.g. accesses to globalsor captured pointers).

If thememory attribute is not specified, thenmemory(readwrite)is implied (all memory effects are possible).

The memory effects of a call can be computed asCallSiteEffects&(FunctionEffects|OperandBundleEffects). Thus, thecall-site annotation takes precedence over the potential effects describedby either the function annotation or the operand bundles.

minsize

This attribute suggests that optimization passes and code generatorpasses make choices that keep the code size of this function as smallas possible and perform optimizations that may sacrifice runtimeperformance in order to minimize the size of the generated code.This attribute is incompatible with theoptdebug andoptnoneattributes.

naked

This attribute disables prologue / epilogue emission for thefunction. This can have very system-specific consequences. The arguments ofanaked function can not be referenced through IR values.

"no-inline-line-tables"

When this attribute is set to true, the inliner discards source locationswhen inlining code and instead uses the source location of the call site.Breakpoints set on code that was inlined into the current function willnot fire during the execution of the inlined call sites. If the debuggerstops inside an inlined call site, it will appear to be stopped at theoutermost inlined call site.

no-jump-tables

When this attribute is set to true, the jump tables and lookup tables thatcan be generated from a switch case lowering are disabled.

nobuiltin

This indicates that the callee function at a call site is not recognized asa built-in function. LLVM will retain the original call and not replace itwith equivalent code based on the semantics of the built-in function, unlessthe call site uses thebuiltin attribute. This is valid at call sitesand on function declarations and definitions.

nocallback

This attribute indicates that the function is only allowed to jump back intocaller’s module by a return or an exception, and is not allowed to jump backby invoking a callback function, a direct, possibly transitive, externalfunction call, use oflongjmp, or other means. It is a compiler hint thatis used at module level to improve dataflow analysis, dropped during linking,and has no effect on functions defined in the current module.

nodivergencesource

A call to this function is not a source of divergence. In uniformityanalysis, asource of divergence is an instruction that generatesdivergence even if its inputs are uniform. A call with no further informationwould normally be considered a source of divergence; setting this attributeon a function means that a call to it is not a source of divergence.

noduplicate

This attribute indicates that calls to the function cannot beduplicated. A call to anoduplicate function may be movedwithin its parent function, but may not be duplicated withinits parent function.

A function containing anoduplicate call may stillbe an inlining candidate, provided that the call is notduplicated by inlining. That implies that the function hasinternal linkage and only has one call site, so the originalcall is dead after inlining.

nofree

This function attribute indicates that the function does not, directly ortransitively, call a memory-deallocation function (free, for example)on a memory allocation which existed before the call.

As a result, uncaptured pointers that are known to be dereferenceableprior to a call to a function with thenofree attribute are stillknown to be dereferenceable after the call. The capturing condition isnecessary in environments where the function might communicate thepointer to another thread which then deallocates the memory. Alternatively,nosync would ensure such communication cannot happen and even capturedpointers cannot be freed by the function.

Anofree function is explicitly allowed to free memory which itallocated or (if notnosync) arrange for another thread to freememory on it’s behalf. As a result, perhaps surprisingly, anofreefunction can return a pointer to a previously deallocatedallocated object.

noimplicitfloat

Disallows implicit floating-point code. This inhibits optimizations thatuse floating-point code and floating-point registers for operations that arenot nominally floating-point. LLVM instructions that perform floating-pointoperations or require access to floating-point registers may still causefloating-point code to be generated.

Also inhibits optimizations that create SIMD/vector code and registers fromscalar code such as vectorization or memcpy/memset optimization. Thisincludes integer vectors. Vector instructions present in IR may still causevector code to be generated.

noinline

This attribute indicates that the inliner should never inline thisfunction in any situation. This attribute may not be used togetherwith thealwaysinline attribute.

nomerge

This attribute indicates that calls to this function should never be mergedduring optimization. For example, it will prevent tail merging otherwiseidentical code sequences that raise an exception or terminate the program.Tail merging normally reduces the precision of source location information,making stack traces less useful for debugging. This attribute gives theuser control over the tradeoff between code size and debug informationprecision.

nonlazybind

This attribute suppresses lazy symbol binding for the function. Thismay make calls to the function faster, at the cost of extra programstartup time if the function is not called during program startup.

noprofile

This function attribute prevents instrumentation based profiling, used forcoverage or profile based optimization, from being added to a function. Italso blocks inlining if the caller and callee have different values of thisattribute.

skipprofile

This function attribute prevents instrumentation based profiling, used forcoverage or profile based optimization, from being added to a function. Thisattribute does not restrict inlining, so instrumented instruction could endup in this function.

noredzone

This attribute indicates that the code generator should not use ared zone, even if the target-specific ABI normally permits it.

indirect-tls-seg-refs

This attribute indicates that the code generator should not usedirect TLS access through segment registers, even if thetarget-specific ABI normally permits it.

noreturn

This function attribute indicates that the function never returnsnormally, hence through a return instruction. This produces undefinedbehavior at runtime if the function ever does dynamically return. Annotatedfunctions may still raise an exception, i.a.,nounwind is not implied.

norecurse

This function attribute indicates that the function does not call itselfeither directly or indirectly down any possible call path. This producesundefined behavior at runtime if the function ever does recurse.

willreturn

This function attribute indicates that a call of this function willeither exhibit undefined behavior or comes back and continues executionat a point in the existing call stack that includes the current invocation.Annotated functions may still raise an exception, i.a.,nounwind is not implied.If an invocation of an annotated function does not return control backto a point in the call stack, the behavior is undefined.

nosync

This function attribute indicates that the function does not communicate(synchronize) with another thread through memory or other well-defined means.Synchronization is considered possible in the presence ofatomic accessesthat enforce an order, thus not “unordered” and “monotonic”,volatile accesses,as well asconvergent function calls.

Note thatconvergent operations can involve communication that isconsidered to be not through memory and does not necessarily imply anordering between threads for the purposes of the memory model. Therefore,an operation can be bothconvergent andnosync.

If anosync function does ever synchronize with another thread,the behavior is undefined.

nounwind

This function attribute indicates that the function never raises anexception. If the function does raise an exception, its runtimebehavior is undefined. However, functions marked nounwind may stilltrap or generate asynchronous exceptions. Exception handling schemesthat are recognized by LLVM to handle asynchronous exceptions, suchas SEH, will still provide their implementation defined semantics.

nosanitize_bounds

This attribute indicates that bounds checking sanitizer instrumentationis disabled for this function.

nosanitize_coverage

This attribute indicates that SanitizerCoverage instrumentation is disabledfor this function.

null_pointer_is_valid

Ifnull_pointer_is_valid is set, then thenull addressin address-space 0 is considered to be a valid address for memory loads andstores. Any analysis or optimization should not treat dereferencing apointer tonull as undefined behavior in this function.Note: Comparing address of a global variable tonull may stillevaluate to false because of a limitation in querying this attribute insideconstant expressions.

optdebug

This attribute suggests that optimization passes and code generator passesshould make choices that try to preserve debug info without significantlydegrading runtime performance.This attribute is incompatible with theminsize,optsize, andoptnone attributes.

optforfuzzing

This attribute indicates that this function should be optimizedfor maximum fuzzing signal.

optnone

This function attribute indicates that most optimization passes will skipthis function, with the exception of interprocedural optimization passes.Code generation defaults to the “fast” instruction selector.This attribute cannot be used together with thealwaysinlineattribute; this attribute is also incompatiblewith theminsize,optsize, andoptdebug attributes.

This attribute requires thenoinline attribute to be specified onthe function as well, so the function is never inlined into any caller.Only functions with thealwaysinline attribute are validcandidates for inlining into the body of this function.

optsize

This attribute suggests that optimization passes and code generatorpasses make choices that keep the code size of this function low,and otherwise do optimizations specifically to reduce code size aslong as they do not significantly impact runtime performance.This attribute is incompatible with theoptdebug andoptnoneattributes.

"patchable-function"

This attribute tells the code generator that the codegenerated for this function needs to follow certain conventions thatmake it possible for a runtime function to patch over it later.The exact effect of this attribute depends on its string value,for which there currently is one legal possibility:

• "prologue-short-redirect" - This style of patchablefunction is intended to support patching a function prologue toredirect control away from the function in a thread safemanner. It guarantees that the first instruction of thefunction will be large enough to accommodate a short jumpinstruction, and will be sufficiently aligned to allow beingfully changed via an atomic compare-and-swap instruction.While the first requirement can be satisfied by inserting largeenough NOP, LLVM can and will try to re-purpose an existinginstruction (i.e. one that would have to be emitted anyway) asthe patchable instruction larger than a short jump.

  "prologue-short-redirect" is currently only supported onx86-64.

This attribute by itself does not imply restrictions oninter-procedural optimizations. All of the semantic effects thepatching may have to be separately conveyed via the linkage type.

"probe-stack"

This attribute indicates that the function will trigger a guard regionin the end of the stack. It ensures that accesses to the stack must beno further apart than the size of the guard region to a previousaccess of the stack. It takes one required string value, the name ofthe stack probing function that will be called.

If a function that has a"probe-stack" attribute is inlined intoa function with another"probe-stack" attribute, the resultingfunction has the"probe-stack" attribute of the caller. If afunction that has a"probe-stack" attribute is inlined into afunction that has no"probe-stack" attribute at all, the resultingfunction has the"probe-stack" attribute of the callee.

"stack-probe-size"

This attribute controls the behavior of stack probes: eitherthe"probe-stack" attribute, or ABI-required stack probes, if any.It defines the size of the guard region. It ensures that if the functionmay use more stack space than the size of the guard region, stack probingsequence will be emitted. It takes one required integer value, whichis 4096 by default.

If a function that has a"stack-probe-size" attribute is inlined intoa function with another"stack-probe-size" attribute, the resultingfunction has the"stack-probe-size" attribute that has the lowernumeric value. If a function that has a"stack-probe-size" attribute isinlined into a function that has no"stack-probe-size" attributeat all, the resulting function has the"stack-probe-size" attributeof the callee.

"no-stack-arg-probe"

This attribute disables ABI-required stack probes, if any.

returns_twice

This attribute indicates that this function can return twice. The Csetjmp is an example of such a function. The compiler disablessome optimizations (like tail calls) in the caller of thesefunctions.

safestack

This attribute indicates thatSafeStackprotection is enabled for this function.

If a function that has asafestack attribute is inlined into afunction that doesn’t have asafestack attribute or which has anssp,sspstrong orsspreq attribute, then the resultingfunction will have asafestack attribute.

sanitize_address

This attribute indicates that AddressSanitizer checks(dynamic address safety analysis) are enabled for this function.

sanitize_memory

This attribute indicates that MemorySanitizer checks (dynamic detectionof accesses to uninitialized memory) are enabled for this function.

sanitize_thread

This attribute indicates that ThreadSanitizer checks(dynamic thread safety analysis) are enabled for this function.

sanitize_hwaddress

This attribute indicates that HWAddressSanitizer checks(dynamic address safety analysis based on tagged pointers) are enabled forthis function.

sanitize_memtag

This attribute indicates that MemTagSanitizer checks(dynamic address safety analysis based on Armv8 MTE) are enabled forthis function.

sanitize_realtime

This attribute indicates that RealtimeSanitizer checks(realtime safety analysis - no allocations, syscalls or exceptions) are enabledfor this function.

sanitize_realtime_blocking

This attribute indicates that RealtimeSanitizer should error immediatelyif the attributed function is called during invocation of a functionattributed withsanitize_realtime.This attribute is incompatible with thesanitize_realtime attribute.

speculative_load_hardening

This attribute indicates thatSpeculative Load Hardeningshould be enabled for the function body.

Speculative Load Hardening is a best-effort mitigation againstinformation leak attacks that make use of control flowmiss-speculation - specifically miss-speculation of whether a branchis taken or not. Typically vulnerabilities enabling such attacks areclassified as “Spectre variant #1”. Notably, this does not attempt tomitigate against miss-speculation of branch target, classified as“Spectre variant #2” vulnerabilities.

When inlining, the attribute is sticky. Inlining a function that carriesthis attribute will cause the caller to gain the attribute. This is intendedto provide a maximally conservative model where the code in a functionannotated with this attribute will always (even after inlining) end uphardened.

speculatable

This function attribute indicates that the function does not have anyeffects besides calculating its result and does not have undefined behavior.Note thatspeculatable is not enough to conclude that along anyparticular execution path the number of calls to this function will not beexternally observable. This attribute is only valid on functionsand declarations, not on individual call sites. If a function isincorrectly marked as speculatable and really does exhibitundefined behavior, the undefined behavior may be observed evenif the call site is dead code.

ssp

This attribute indicates that the function should emit a stacksmashing protector. It is in the form of a “canary” — a random valueplaced on the stack before the local variables that’s checked uponreturn from the function to see if it has been overwritten. Aheuristic is used to determine if a function needs stack protectorsor not. The heuristic used will enable protectors for functions with:

• Character arrays larger thanssp-buffer-size (default 8).

• Aggregates containing character arrays larger thanssp-buffer-size.

• Calls to alloca() with variable sizes or constant sizes greater thanssp-buffer-size.

Variables that are identified as requiring a protector will be arrangedon the stack such that they are adjacent to the stack protector guard.

If a function with anssp attribute is inlined into a calling function,the attribute is not carried over to the calling function.

sspstrong

This attribute indicates that the function should emit a stack smashingprotector. This attribute causes a strong heuristic to be used whendetermining if a function needs stack protectors. The strong heuristicwill enable protectors for functions with:

• Arrays of any size and type

• Aggregates containing an array of any size and type.

• Calls to alloca().

• Local variables that have had their address taken.

Variables that are identified as requiring a protector will be arrangedon the stack such that they are adjacent to the stack protector guard.The specific layout rules are:

1. Large arrays and structures containing large arrays(>=ssp-buffer-size) are closest to the stack protector.

2. Small arrays and structures containing small arrays(<ssp-buffer-size) are 2nd closest to the protector.

3. Variables that have had their address taken are 3rd closest to theprotector.

This overrides thessp function attribute.

If a function with ansspstrong attribute is inlined into a callingfunction which has anssp attribute, the calling function’s attributewill be upgraded tosspstrong.

sspreq

This attribute indicates that the function shouldalways emit a stacksmashing protector. This overrides thessp andsspstrong functionattributes.

Variables that are identified as requiring a protector will be arrangedon the stack such that they are adjacent to the stack protector guard.The specific layout rules are:

1. Large arrays and structures containing large arrays(>=ssp-buffer-size) are closest to the stack protector.

2. Small arrays and structures containing small arrays(<ssp-buffer-size) are 2nd closest to the protector.

3. Variables that have had their address taken are 3rd closest to theprotector.

If a function with ansspreq attribute is inlined into a callingfunction which has anssp orsspstrong attribute, the callingfunction’s attribute will be upgraded tosspreq.

strictfp

This attribute indicates that the function was called from a scope thatrequires strict floating-point semantics. LLVM will not attempt anyoptimizations that require assumptions about the floating-point roundingmode or that might alter the state of floating-point status flags thatmight otherwise be set or cleared by calling this function. LLVM willnot introduce any new floating-point instructions that may trap.

"denormal-fp-math"

This indicates the denormal (subnormal) handling that may beassumed for the default floating-point environment. This is acomma separated pair. The elements may be one of"ieee","preserve-sign","positive-zero", or"dynamic". Thefirst entry indicates the flushing mode for the result of floatingpoint operations. The second indicates the handling of denormal inputsto floating point instructions. For compatibility with olderbitcode, if the second value is omitted, both input and outputmodes will assume the same mode.

If this is attribute is not specified, the default is"ieee,ieee".

If the output mode is"preserve-sign", or"positive-zero",denormal outputs may be flushed to zero by standard floating-pointoperations. It is not mandated that flushing to zero occurs, but ifa denormal output is flushed to zero, it must respect the signmode. Not all targets support all modes.

If the mode is"dynamic", the behavior is derived from thedynamic state of the floating-point environment. Transformationswhich depend on the behavior of denormal values should not beperformed.

While this indicates the expected floating point mode the functionwill be executed with, this does not make any attempt to ensurethe mode is consistent. User or platform code is expected to setthe floating point mode appropriately before function entry.

If the input mode is"preserve-sign", or"positive-zero",a floating-point operation must treat any input denormal value aszero. In some situations, if an instruction does not respect thismode, the input may need to be converted to 0 as if by@llvm.canonicalize during lowering for correctness.

"denormal-fp-math-f32"

Same as"denormal-fp-math", but only controls the behavior ofthe 32-bit float type (or vectors of 32-bit floats). If both areare present, this overrides"denormal-fp-math". Not all targetssupport separately setting the denormal mode per type, and noattempt is made to diagnose unsupported uses. Currently thisattribute is respected by the AMDGPU and NVPTX backends.

"thunk"

This attribute indicates that the function will delegate to some otherfunction with a tail call. The prototype of a thunk should not be used foroptimization purposes. The caller is expected to cast the thunk prototype tomatch the thunk target prototype.

uwtable[(sync|async)]

This attribute indicates that the ABI being targeted requires thatan unwind table entry be produced for this function even if we canshow that no exceptions passes by it. This is normally the case forthe ELF x86-64 abi, but it can be disabled for some compilationunits. The optional parameter describes what kind of unwind tablesto generate:sync for normal unwind tables,async for asynchronous(instruction precise) unwind tables. Without the parameter, the attributeuwtable is equivalent touwtable(async).

nocf_check

This attribute indicates that no control-flow check will be performed onthe attributed entity. It disables -fcf-protection=<> for a specificentity to fine grain the HW control flow protection mechanism. The flagis target independent and currently appertains to a function or functionpointer.

shadowcallstack

This attribute indicates that the ShadowCallStack checks are enabled forthe function. The instrumentation checks that the return address for thefunction has not changed between the function prolog and epilog. It iscurrently x86_64-specific.

mustprogress

This attribute indicates that the function is required to return, unwind,or interact with the environment in an observable way e.g. via a volatilememory access, I/O, or other synchronization. Themustprogressattribute is intended to model the requirements of the first section of[intro.progress] of the C++ Standard. As a consequence, a loop in afunction with themustprogress attribute can be assumed to terminate ifit does not interact with the environment in an observable way, andterminating loops without side-effects can be removed. If amustprogressfunction does not satisfy this contract, the behavior is undefined. If amustprogress function calls a function not markedmustprogress,and that function never returns, the program is well-defined even if thereisn’t any other observable progress. Note thatwillreturn impliesmustprogress.

"warn-stack-size"="<threshold>"

This attribute sets a threshold to emit diagnostics once the frame size isknown should the frame size exceed the specified value. It takes onerequired integer value, which should be a non-negative integer, and lessthanUINT_MAX. It’s unspecified which threshold will be used whenduplicate definitions are linked together with differing values.

vscale_range(<min>[,<max>])

This function attribute indicatesvscale is a power-of-two within aspecified range.min must be a power-of-two that is greater than 0. Whenspecified,max must be a power-of-two greater-than-or-equal tomin or 0to signify an unbounded maximum. The syntaxvscale_range(<val>) can beused to set bothmin andmax to the same value. Functions that don’tinclude this attribute make no assumptions about the value ofvscale.

"nooutline"

This attribute indicates that outlining passes should not modify thefunction.

Call Site Attributes¶

In addition to function attributes the following call site onlyattributes are supported:

vector-function-abi-variant

This attribute can be attached to acall to listthe vector functions associated to the function. Notice that theattribute cannot be attached to ainvoke or acallbr instruction. The attribute consists of acomma separated list of mangled names. The order of the list doesnot imply preference (it is logically a set). The compiler is freeto pick any listed vector function of its choosing.

The syntax for the mangled names is as follows::

_ZGV<isa><mask><vlen><parameters>_<scalar_name>[(<vector_redirection>)]

When present, the attribute informs the compiler that the function<scalar_name> has a corresponding vector variant that can beused to perform the concurrent invocation of<scalar_name> onvectors. The shape of the vector function is described by thetokens between the prefix_ZGV and the<scalar_name>token. The standard name of the vector function is_ZGV<isa><mask><vlen><parameters>_<scalar_name>. When present,the optional token(<vector_redirection>) informs the compilerthat a custom name is provided in addition to the standard one(custom names can be provided for example via the use ofdeclarevariant in OpenMP 5.0). The declaration of the variant must bepresent in the IR Module. The signature of the vector variant isdetermined by the rules of the Vector Function ABI (VFABI)specifications of the target. For Arm and X86, the VFABI can befound athttps://github.com/ARM-software/abi-aa andhttps://software.intel.com/content/www/us/en/develop/download/vector-simd-function-abi.html,respectively.

For X86 and Arm targets, the values of the tokens in the standardname are those that are defined in the VFABI. LLVM has an internal<isa> token that can be used to create scalar-to-vectormappings for functions that are not directly associated to any ofthe target ISAs (for example, some of the mappings stored in theTargetLibraryInfo). Valid values for the<isa> token are::

<isa>:=b|c|d|e->X86SSE,AVX,AVX2,AVX512|n|s->Armv8AdvancedSIMD,SVE|__LLVM__->InternalLLVMVectorISA

For all targets currently supported (x86, Arm and Internal LLVM),the remaining tokens can have the following values::

<mask>:=M|N->mask|nomask<vlen>:=number->numberoflanes|x->VLA(VectorLengthAgnostic)<parameters>:=v->vector|l|l<number>->linear|R|R<number>->linearwithrefmodifier|L|L<number>->linearwithvalmodifier|U|U<number>->linearwithuvalmodifier|ls<pos>->runtimelinear|Rs<pos>->runtimelinearwithrefmodifier|Ls<pos>->runtimelinearwithvalmodifier|Us<pos>->runtimelinearwithuvalmodifier|u->uniform<scalar_name>:=nameofthescalarfunction<vector_redirection>:=optional,customnameofthevectorfunction

preallocated(<ty>)

This attribute is required on calls tollvm.call.preallocated.argand cannot be used on any other call. Seellvm.call.preallocated.arg for moredetails.

Global Attributes¶

Attributes may be set to communicate additional information about a global variable.Unlikefunction attributes, attributes on a global variableare grouped into a singleattribute group.

no_sanitize_address

This attribute indicates that the global variable should not haveAddressSanitizer instrumentation applied to it, because it was annotatedwith__attribute__((no_sanitize(“address”))),__attribute__((disable_sanitizer_instrumentation)), or included in the-fsanitize-ignorelist file.

no_sanitize_hwaddress

This attribute indicates that the global variable should not haveHWAddressSanitizer instrumentation applied to it, because it was annotatedwith__attribute__((no_sanitize(“hwaddress”))),__attribute__((disable_sanitizer_instrumentation)), or included in the-fsanitize-ignorelist file.

sanitize_memtag

This attribute indicates that the global variable should have AArch64 memorytags (MTE) instrumentation applied to it. This attribute causes thesuppression of certain optimizations, like GlobalMerge, as well as ensuringextra directives are emitted in the assembly and extra bits of metadata areplaced in the object file so that the linker can ensure the accesses areprotected by MTE. This attribute is added by clang when-fsanitize=memtag-globals is provided, as long as the global is not markedwith__attribute__((no_sanitize(“memtag”))),__attribute__((disable_sanitizer_instrumentation)), or included in the-fsanitize-ignorelist file. The AArch64 Globals Tagging pass may removethis attribute when it’s not possible to tag the global (e.g. it’s a TLSvariable).

sanitize_address_dyninit

This attribute indicates that the global variable, when instrumented withAddressSanitizer, should be checked for ODR violations. This attribute isapplied to global variables that are dynamically initialized according toC++ rules.

Operand Bundles¶

Operand bundles are tagged sets of SSA values or metadata strings that can beassociated with certain LLVM instructions (currently onlycall s andinvoke s). In a way they are like metadata, but dropping them isincorrect and will change program semantics.

Syntax:

operandbundleset::='['operandbundle(,operandbundle)*']'operandbundle::=tag'('[bundleoperand](,bundleoperand)*')'bundleoperand::=SSAvalue|metadatastringtag::=stringconstant

Operand bundles arenot part of a function’s signature, and agiven function may be called from multiple places with different kindsof operand bundles. This reflects the fact that the operand bundlesare conceptually a part of thecall (orinvoke), not thecallee being dispatched to.

Operand bundles are a generic mechanism intended to supportruntime-introspection-like functionality for managed languages. Whilethe exact semantics of an operand bundle depend on the bundle tag,there are certain limitations to how much the presence of an operandbundle can influence the semantics of a program. These restrictionsare described as the semantics of an “unknown” operand bundle. Aslong as the behavior of an operand bundle is describable within theserestrictions, LLVM does not need to have special knowledge of theoperand bundle to not miscompile programs containing it.

• The bundle operands for an unknown operand bundle escape in unknownways before control is transferred to the callee or invokee.

• Calls and invokes with operand bundles have unknown read / writeeffect on the heap on entry and exit (even if the call target specifiesamemory attribute), unless they’re overridden withcallsite specific attributes.

• An operand bundle at a call site cannot change the implementationof the called function. Inter-procedural optimizations work asusual as long as they take into account the first two properties.

More specific types of operand bundles are described below.

definevoid@f(){callvoid@x();; no deopt statecallvoid@y()["deopt"(i3210)]callvoid@y()["deopt"(i3210),"unknown"(ptrnull)]retvoid}definevoid@g(){callvoid@f()["deopt"(i3220)]retvoid}

definevoid@g(){callvoid@x();; still no deopt statecallvoid@y()["deopt"(i3220,i3210)]callvoid@y()["deopt"(i3220,i3210),"unknown"(ptrnull)]retvoid}

"<tag>"([<arguments>]])

"<tag>"([<holdsforvalue>[,<attributeargument>]])

callvoid@llvm.assume(i1true)["align"(ptr%val,i328)]

callvoid@llvm.assume(i1%cond)["cold"(),"nonnull"(ptr%val)]

callvoid@llvm.assume(i1true)["align"(ptr%val,i32%align)]

separate_storage(<val1>,<val2>)``

%foo=type{i64,i32}...%t=calltoken@llvm.call.preallocated.setup(i321)%a=callptr@llvm.call.preallocated.arg(token%t,i320)preallocated(%foo); initialize %bcallvoid@bar(i3242,ptrpreallocated(%foo)%a)["preallocated"(token%t)]

; The marker instruction and a runtime function call are inserted after the call; to @foo.callptr@foo()["clang.arc.attachedcall"(ptr@objc_retainAutoreleasedReturnValue)]callptr@foo()["clang.arc.attachedcall"(ptr@objc_unsafeClaimAutoreleasedReturnValue)]

callvoid%0()["kcfi"(i321234)]

Module-Level Inline Assembly¶

Modules may contain “module-level inline asm” blocks, which correspondsto the GCC “file scope inline asm” blocks. These blocks are internallyconcatenated by LLVM and treated as a single unit, but may be separatedin the.ll file if desired. The syntax is very simple:

moduleasm"inline asm code goes here"moduleasm"more can go here"

The strings can contain any character by escaping non-printablecharacters. The escape sequence used is simply “\xx” where “xx” is thetwo digit hex code for the number.

Note that the assembly stringmust be parseable by LLVM’s integrated assembler(unless it is disabled), even when emitting a.s file.

Data Layout¶

A module may specify a target specific data layout string that specifieshow data is to be laid out in memory. The syntax for the data layout issimply:

targetdatalayout="layout specification"

Thelayout specification consists of a list of specificationsseparated by the minus sign character (‘-‘). Each specification startswith a letter and may include other information after the letter todefine some aspect of the data layout. The specifications accepted areas follows:

E

Specifies that the target lays out data in big-endian form. That is,the bits with the most significance have the lowest addresslocation.

e

Specifies that the target lays out data in little-endian form. Thatis, the bits with the least significance have the lowest addresslocation.

S<size>

Specifies the natural alignment of the stack in bits. Alignmentpromotion of stack variables is limited to the natural stackalignment to avoid dynamic stack realignment. If omitted, the natural stackalignment defaults to “unspecified”, which does not prevent anyalignment promotions.

P<addressspace>

Specifies the address space that corresponds to program memory.Harvard architectures can use this to specify what space LLVMshould place things such as functions into. If omitted, theprogram memory space defaults to the default address space of 0,which corresponds to a Von Neumann architecture that has codeand data in the same space.

G<addressspace>

Specifies the address space to be used by default when creating globalvariables. If omitted, the globals address space defaults to the defaultaddress space 0.Note: variable declarations without an address space are always created inaddress space 0, this property only affects the default value to be usedwhen creating globals without additional contextual information (e.g. inLLVM passes).

A<addressspace>

Specifies the address space of objects created by ‘alloca’.Defaults to the default address space of 0.

p[n]:<size>:<abi>[:<pref>[:<idx>]]

This specifies the properties of a pointer in address spacen.The<size> parameter specifies the size of the bitwise representation.Fornon-integral pointers the representation size maybe larger than the address width of the underlying address space (e.g. toaccommodate additional metadata).The alignment requirements are specified via the<abi> and<pref>erred alignments parameters.The fourth parameter<idx> is the size of the index that used foraddress calculations such asgetelementptr.It must be less than or equal to the pointer size. If not specified, thedefault index size is equal to the pointer size.The index size also specifies the width of addresses in this address space.All sizes are in bits.The address space,n, is optional, and if not specified,denotes the default address space 0. The value ofn must bein the range [1,2^24).

i<size>:<abi>[:<pref>]

This specifies the alignment for an integer type of a given bit<size>. The value of<size> must be in the range [1,2^24).Fori8, the<abi> value must equal 8,that is,i8 must be naturally aligned.

v<size>:<abi>[:<pref>]

This specifies the alignment for a vector type of a given bit<size>. The value of<size> must be in the range [1,2^24).

f<size>:<abi>[:<pref>]

This specifies the alignment for a floating-point type of a given bit<size>. Only values of<size> that are supported by the targetwill work. 32 (float) and 64 (double) are supported on all targets; 80or 128 (different flavors of long double) are also supported on sometargets. The value of<size> must be in the range [1,2^24).

a:<abi>[:<pref>]

This specifies the alignment for an object of aggregate type.In addition to the usual requirements for alignment values,the value of<abi> can also be zero, which means one byte alignment.

F<type><abi>

This specifies the alignment for function pointers.The options for<type> are:

• i: The alignment of function pointers is independent of the alignmentof functions, and is a multiple of<abi>.

• n: The alignment of function pointers is a multiple of the explicitalignment specified on the function, and is a multiple of<abi>.

m:<mangling>

If present, specifies that llvm names are mangled in the output. Symbolsprefixed with the mangling escape character\01 are passed throughdirectly to the assembler without the escape character. The mangling styleoptions are

• e: ELF mangling: Private symbols get a.L prefix.

• l: GOFF mangling: Private symbols get a@ prefix.

• m: Mips mangling: Private symbols get a$ prefix.

• o: Mach-O mangling: Private symbols getL prefix. Othersymbols get a_ prefix.

• x: Windows x86 COFF mangling: Private symbols get the usual prefix.Regular C symbols get a_ prefix. Functions with__stdcall,__fastcall, and__vectorcall have custom mangling that appends@N where N is the number of bytes used to pass parameters. C++ symbolsstarting with? are not mangled in any way.

• w: Windows COFF mangling: Similar tox, except that normal Csymbols do not receive a_ prefix.

• a: XCOFF mangling: Private symbols get aL.. prefix.

n<size1>:<size2>:<size3>...

This specifies a set of native integer widths for the target CPU inbits. For example, it might containn32 for 32-bit PowerPC,n32:64 for PowerPC 64, orn8:16:32:64 for X86-64. Elements ofthis set are considered to support most general arithmetic operationsefficiently.

ni:<addressspace0>:<addressspace1>:<addressspace2>...

This specifies pointer types with the specified address spacesasNon-Integral Pointer Type s. The0address space cannot be specified as non-integral.

<abi> is a lower bound on what is required for a type to be consideredaligned. This is used in various places, such as:

• The alignment for loads and stores if none is explicitly given.

• The alignment used to compute struct layout.

• The alignment used to compute allocation sizes and thusgetelementptroffsets.

• The alignment below which accesses are considered underaligned.

<pref> allows providing a more optimal alignment that should be used whenpossible, primarily foralloca and the alignment of global variables. It isan optional value that must be greater than or equal to<abi>. If omitted,the preceding: should also be omitted and<pref> will be equal to<abi>.

Unless explicitly stated otherwise, every alignment specification is provided inbits and must be in the range [1,2^16). The value must be a power of two timesthe width of a byte (i.e.align=8*2^N).

When constructing the data layout for a given target, LLVM starts with adefault set of specifications which are then (possibly) overridden bythe specifications in thedatalayout keyword. The defaultspecifications are given in this list:

• e - little endian

• p:64:64:64 - 64-bit pointers with 64-bit alignment.

• p[n]:64:64:64 - Other address spaces are assumed to be thesame as the default address space.

• S0 - natural stack alignment is unspecified

• i1:8:8 - i1 is 8-bit (byte) aligned

• i8:8:8 - i8 is 8-bit (byte) aligned as mandated

• i16:16:16 - i16 is 16-bit aligned

• i32:32:32 - i32 is 32-bit aligned

• i64:32:64 - i64 has ABI alignment of 32-bits but preferredalignment of 64-bits

• f16:16:16 - half is 16-bit aligned

• f32:32:32 - float is 32-bit aligned

• f64:64:64 - double is 64-bit aligned

• f128:128:128 - quad is 128-bit aligned

• v64:64:64 - 64-bit vector is 64-bit aligned

• v128:128:128 - 128-bit vector is 128-bit aligned

• a:0:64 - aggregates are 64-bit aligned

When LLVM is determining the alignment for a given type, it uses thefollowing rules:

1. If the type sought is an exact match for one of the specifications,that specification is used.

2. If no match is found, and the type sought is an integer type, thenthe smallest integer type that is larger than the bitwidth of thesought type is used. If none of the specifications are larger thanthe bitwidth then the largest integer type is used. For example,given the default specifications above, the i7 type will use thealignment of i8 (next largest) while both i65 and i256 will use thealignment of i64 (largest specified).

The function of the data layout string may not be what you expect.Notably, this is not a specification from the frontend of what alignmentthe code generator should use.

Instead, if specified, the target data layout is required to match whatthe ultimatecode generator expects. This string is used by themid-level optimizers to improve code, and this only works if it matcheswhat the ultimate code generator uses. There is no way to generate IRthat does not embed this target-specific detail into the IR. If youdon’t specify the string, the default specifications will be used togenerate a Data Layout and the optimization phases will operateaccordingly and introduce target specificity into the IR with respect tothese default specifications.

Target Triple¶

A module may specify a target triple string that describes the targethost. The syntax for the target triple is simply:

targettriple="x86_64-apple-macosx10.7.0"

Thetarget triple string consists of a series of identifiers delimitedby the minus sign character (‘-‘). The canonical forms are:

ARCHITECTURE-VENDOR-OPERATING_SYSTEMARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT

This information is passed along to the backend so that it generatescode for the proper architecture. It’s possible to override this on thecommand line with the-mtriple command line option.

Allocated Objects¶

An allocated object, memory object, or simply object, is a region of a memoryspace that is reserved by a memory allocation such asalloca,heap allocation calls, and global variable definitions. Once it is allocated,the bytes stored in the region can only be read or written through a pointerthat isbased on the allocation value. If a pointerthat is not based on the object tries to read or write to the object, it isundefined behavior.

The following properties hold for all allocated objects, otherwise thebehavior is undefined:

• no allocated object may cross the unsigned address space boundary (includingthe pointer after the end of the object),

• the size of all allocated objects must be non-negative and not exceed thelargest signed integer that fits into the index type.

Object Lifetime¶

A lifetime of anallocated object is a property thatdecides its accessibility. Unless stated otherwise, an allocated object is alivesince its allocation, and dead after its deallocation. It is undefined behaviorto access an allocated object that isn’t alive, but operations that don’tdereference it such asgetelementptr,ptrtoint andicmp return a valid result.This explains code motion of these instructions across operations that impactthe object’s lifetime. A stack object’s lifetime can be explicitly specifiedusingllvm.lifetime.start andllvm.lifetime.end intrinsic function calls.

Pointer Aliasing Rules¶

Any memory access must be done through a pointer value associated withan address range of the memory access, otherwise the behavior isundefined. Pointer values are associated with address ranges accordingto the following rules:

• A pointer value is associated with the addresses associated with anyvalue it isbased on.

• An address of a global variable is associated with the address rangeof the variable’s storage.

• The result value of an allocation instruction is associated with theaddress range of the allocated storage.

• A null pointer in the default address-space is associated with noaddress.

• Anundef value inany address-space isassociated with no address.

• An integer constant other than zero or a pointer value returned froma function not defined within LLVM may be associated with addressranges allocated through mechanisms other than those provided byLLVM. Such ranges shall not overlap with any ranges of addressesallocated by mechanisms provided by LLVM.

A pointer value isbased on another pointer value according to thefollowing rules:

• A pointer value formed from a scalargetelementptr operation isbased onthe pointer-typed operand of thegetelementptr.

• The pointer in lanel of the result of a vectorgetelementptr operationisbased on the pointer in lanel of the vector-of-pointers-typed operandof thegetelementptr.

• The result value of abitcast isbased on the operand of thebitcast.

• A pointer value formed by aninttoptr isbased on all pointervalues that contribute (directly or indirectly) to the computation ofthe pointer’s value.

• The “based on” relationship is transitive.

Note that this definition of“based” is intentionally similar to thedefinition of“based” in C99, though it is slightly weaker.

LLVM IR does not associate types with memory. The result type of aload merely indicates the size and alignment of the memory fromwhich to load, as well as the interpretation of the value. The firstoperand type of astore similarly only indicates the size andalignment of the store.

Consequently, type-based alias analysis, aka TBAA, aka-fstrict-aliasing, is not applicable to general unadorned LLVM IR.Metadata may be used to encode additional informationwhich specialized optimization passes may use to implement type-basedalias analysis.

Pointer Capture¶

Given a function call and a pointer that is passed as an argument or stored inmemory before the call, the call may capture two components of the pointer:

• The address of the pointer, which is its integral value. This also includesparts of the address or any information about the address, including thefact that it does not equal one specific value. We further distinguishwhether only the fact that the address is/isn’t null is captured.

• The provenance of the pointer, which is the ability to perform memoryaccesses through the pointer, in the sense of thepointer aliasingrules. We further distinguish whether only read accessesare allowed, or both reads and writes.

For example, the following function captures the address of%a, becauseit is compared to a pointer, leaking information about the identity of thepointer:

@glb=globali80definei1@f(ptr%a){%c=icmpeqptr%a,@glbreti1%c}

The function does not capture the provenance of the pointer, because theicmp instruction only operates on the pointer address. The followingfunction captures both the address and provenance of the pointer, as bothmay be read from@glb after the function returns:

@glb=globalptrnulldefinevoid@f(ptr%a){storeptr%a,ptr@glbretvoid}

The following function capturesneither the address nor the provenance ofthe pointer:

definei32@f(ptr%a){%v=loadi32,ptr%areti32}

While address capture includes uses of the address within the body of thefunction, provenance capture refers exclusively to the ability to performaccessesafter the function returns. Memory accesses within the functionitself are not considered pointer captures.

We can further say that the capture only occurs through a specific location.In the following example, the pointer (both address and provenance) is capturedthrough the return value only:

defineptr@f(ptr%a){%gep=getelementptri8,ptr%a,i644retptr%gep}

However, we always consider direct inspection of the pointer address(e.g. usingptrtoint) to be location-independent. The following exampleisnot considered a return-only capture, even though theptrtointultimately only contributes to the return value:

@lookup=constant[4xi8][i80,i81,i82,i83]defineptr@f(ptr%a){%a.addr=ptrtointptr%atoi64%mask=andi64%a.addr,3%gep=getelementptri8,ptr@lookup,i64%maskretptr%gep}

This definition is chosen to allow capture analysis to continue with the returnvalue in the usual fashion.

The following describes possible ways to capture a pointer in more detail,where unqualified uses of the word “capture” refer to capturing both addressand provenance.

1. The call stores any bit of the pointer carrying information into a place,and the stored bits can be read from the place by the caller after this callexits.

@glb=globalptrnull@glb2=globalptrnull@glb3=globalptrnull@glbi=globali320defineptr@f(ptr%a,ptr%b,ptr%c,ptr%d,ptr%e){storeptr%a,ptr@glb; %a is captured by this callstoreptr%b,ptr@glb2; %b isn't captured because the stored value is overwritten by the store belowstoreptrnull,ptr@glb2storeptr%c,ptr@glb3callvoid@g(); If @g makes a copy of %c that outlives this call (@f), %c is capturedstoreptrnull,ptr@glb3%i=ptrtointptr%dtoi64%j=trunci64%itoi32storei32%j,ptr@glbi; %d is capturedretptr%e; %e is captured}

2. The call stores any bit of the pointer carrying information into a place,and the stored bits can be safely read from the place by another thread viasynchronization.

@lock=globali1truedefinevoid@f(ptr%a){storeptr%a,ptr@glbstoreatomici1false,ptr@lockrelease; %a is captured because another thread can safely read @glbstoreptrnull,ptr@glbretvoid}

3. The call’s behavior depends on any bit of the pointer carrying information(address capture only).

@glb=globali80definevoid@f(ptr%a){%c=icmpeqptr%a,@glbbri1%c,label%BB_EXIT,label%BB_CONTINUE; captures address of %a onlyBB_EXIT:callvoid@exit()unreachableBB_CONTINUE:retvoid}

4. The pointer is used as the pointer operand of a volatile access.

Volatile Memory Accesses¶

Certain memory accesses, such asload’s,store’s, andllvm.memcpy’s may bemarkedvolatile. The optimizers must not change the number ofvolatile operations or change their order of execution relative to othervolatile operations. The optimizersmay change the order of volatileoperations relative to non-volatile operations. This is not Java’s“volatile” and has no cross-thread synchronization behavior.

A volatile load or store may have additional target-specific semantics.Any volatile operation can have side effects, and any volatile operationcan read and/or modify state which is not accessible via a regular loador store in this module. Volatile operations may use addresses which donot point to memory (like MMIO registers). This means the compiler maynot use a volatile operation to prove a non-volatile access to thataddress has defined behavior. This includes addresses typically forbidden,such as the pointer with bit-value 0.

The allowed side-effects for volatile accesses are limited. If anon-volatile store to a given address would be legal, a volatileoperation may modify the memory at that address. A volatile operationmay not modify any other memory accessible by the module being compiled.A volatile operation may not call any code in the current module.

In general (without target specific context), the address space of avolatile operation may not be changed. Different address spaces mayhave different trapping behavior when dereferencing an invalidpointer.

The compiler may assume execution will continue after a volatile operation,so operations which modify memory or may have undefined behavior can behoisted past a volatile operation.

As an exception to the preceding rule, the compiler may not assume executionwill continue after a volatile store operation. This restriction is necessaryto support the somewhat common pattern in C of intentionally storing to aninvalid pointer to crash the program. In the future, it might make sense toallow frontends to control this behavior.

IR-level volatile loads and stores cannot safely be optimized into llvm.memcpyor llvm.memmove intrinsics even when those intrinsics are flagged volatile.Likewise, the backend should never split or merge target-legal volatileload/store instructions. Similarly, IR-level volatile loads and stores cannotchange from integer to floating-point or vice versa.

Memory Model for Concurrent Operations¶

The LLVM IR does not define any way to start parallel threads ofexecution or to register signal handlers. Nonetheless, there areplatform-specific ways to create them, and we define LLVM IR’s behaviorin their presence. This model is inspired by the C++ memory model.

For a more informal introduction to this model, see theLLVM Atomic Instructions and Concurrency Guide.

We define ahappens-before partial order as the least partial orderthat

• Is a superset of single-thread program order, and

• Whenasynchronizes-withb, includes an edge froma tob.Synchronizes-with pairs are introduced by platform-specifictechniques, like pthread locks, thread creation, thread joining,etc., and by atomic instructions. (See alsoAtomic Memory OrderingConstraints).

Note that program order does not introducehappens-before edgesbetween a thread and signals executing inside that thread.

Every (defined) read operation (load instructions, memcpy, atomicloads/read-modify-writes, etc.) R reads a series of bytes written by(defined) write operations (store instructions, atomicstores/read-modify-writes, memcpy, etc.). For the purposes of thissection, initialized globals are considered to have a write of theinitializer which is atomic and happens before any other read or writeof the memory in question. For each byte of a read R, R_bytemay see any write to the same byte, except:

• If write₁ happens before write₂, andwrite₂ happens before R_byte, thenR_byte does not see write₁.

• If R_byte happens before write₃, thenR_byte does not see write₃.

Given that definition, R_byte is defined as follows:

• If R is volatile, the result is target-dependent. (Volatile issupposed to give guarantees which can supportsig_atomic_t inC/C++, and may be used for accesses to addresses that do not behavelike normal memory. It does not generally provide cross-threadsynchronization.)

• Otherwise, if there is no write to the same byte that happens beforeR_byte, R_byte returnsundef for that byte.

• Otherwise, if R_byte may see exactly one write,R_byte returns the value written by that write.

• Otherwise, if R is atomic, and all the writes R_byte maysee are atomic, it chooses one of the values written. See theAtomicMemory Ordering Constraints section for additionalconstraints on how the choice is made.

• Otherwise R_byte returnsundef.

R returns the value composed of the series of bytes it read. Thisimplies that some bytes within the value may beundefwithoutthe entire value beingundef. Note that this only defines thesemantics of the operation; it doesn’t mean that targets will emit morethan one instruction to read the series of bytes.

Note that in cases where none of the atomic intrinsics are used, thismodel places only one restriction on IR transformations on top of whatis required for single-threaded execution: introducing a store to a bytewhich might not otherwise be stored is not allowed in general.(Specifically, in the case where another thread might write to and readfrom an address, introducing a store can change a load that may seeexactly one write into a load that may see multiple writes.)

Atomic Memory Ordering Constraints¶

Atomic instructions (cmpxchg,atomicrmw,fence,atomic load, andatomic store) takeordering parameters that determine which other atomic instructions onthe same address theysynchronize with. These semantics implementthe Java or C++ memory models; if these descriptions aren’t preciseenough, check those specs (see spec references in theatomics guide).fence instructionstreat these orderings somewhat differently since they don’t take anaddress. See that instruction’s documentation for details.

For a simpler introduction to the ordering constraints, see theLLVM Atomic Instructions and Concurrency Guide.

unordered

The set of values that can be read is governed by the happens-beforepartial order. A value cannot be read unless some operation wroteit. This is intended to provide a guarantee strong enough to modelJava’s non-volatile shared variables. This ordering cannot bespecified for read-modify-write operations; it is not strong enoughto make them atomic in any interesting way.

monotonic

In addition to the guarantees ofunordered, there is a singletotal order for modifications bymonotonic operations on eachaddress. All modification orders must be compatible with thehappens-before order. There is no guarantee that the modificationorders can be combined to a global total order for the whole program(and this often will not be possible). The read in an atomicread-modify-write operation (cmpxchg andatomicrmw) reads the value in the modificationorder immediately before the value it writes. If one atomic readhappens before another atomic read of the same address, the laterread must see the same value or a later value in the address’smodification order. This disallows reordering ofmonotonic (orstronger) operations on the same address. If an address is writtenmonotonic-ally by one thread, and other threadsmonotonic-allyread that address repeatedly, the other threads must eventually seethe write. This corresponds to the C/C++memory_order_relaxed.

acquire

In addition to the guarantees ofmonotonic, asynchronizes-with edge may be formed with arelease operation.This is intended to model C/C++’smemory_order_acquire.

release

In addition to the guarantees ofmonotonic, if this operationwrites a value which is subsequently read by anacquireoperation, itsynchronizes-with that operation. Furthermore,this occurs even if the value written by arelease operationhas been modified by a read-modify-write operation before beingread. (Such a set of operations comprises areleasesequence). This corresponds to the C/C++memory_order_release.

acq_rel (acquire+release)

Acts as both anacquire andrelease operation on itsaddress. This corresponds to the C/C++memory_order_acq_rel.

seq_cst (sequentially consistent)

In addition to the guarantees ofacq_rel (acquire for anoperation that only reads,release for an operation that onlywrites), there is a global total order on allsequentially-consistent operations on all addresses. Eachsequentially-consistent read sees the last preceding write to thesame address in this global order. This corresponds to the C/C++memory_order_seq_cst and Javavolatile.

Note: this global total order isnot guaranteed to be fullyconsistent with thehappens-before partial order ifnon-seq_cst accesses are involved. See the C++ standard[atomics.order] sectionfor more details on the exact guarantees.

If an atomic operation is markedsyncscope("singlethread"), it onlysynchronizes with and only participates in the seq_cst total orderings ofother operations running in the same thread (for example, in signal handlers).

If an atomic operation is markedsyncscope("<target-scope>"), where<target-scope> is a target specific synchronization scope, then it is targetdependent if itsynchronizes with and participates in the seq_cst totalorderings of other operations.

Otherwise, an atomic operation that is not markedsyncscope("singlethread")orsyncscope("<target-scope>")synchronizes with and participates in theseq_cst total orderings of other operations that are not markedsyncscope("singlethread") orsyncscope("<target-scope>").

Floating-Point Environment¶

The default LLVM floating-point environment assumes that traps are disabled andstatus flags are not observable. Therefore, floating-point math operations donot have side effects and may be speculated freely. Results assume theround-to-nearest rounding mode, and subnormals are assumed to be preserved.

Running LLVM code in an environment where these assumptions are not mettypically leads to undefined behavior. Thestrictfp anddenormal-fp-mathattributes as well asConstrained Floating-Point Intrinsics can be used to weaken LLVM’s assumptions and ensure definedbehavior in non-default floating-point environments; see their respectivedocumentation for details.

Behavior of Floating-Point NaN values¶

A floating-point NaN value consists of a sign bit, a quiet/signaling bit, and apayload (which makes up the rest of the mantissa except for the quiet/signalingbit). LLVM assumes that the quiet/signaling bit being set to1 indicates aquiet NaN (QNaN), and a value of0 indicates a signaling NaN (SNaN). In thefollowing we will hence just call it the “quiet bit”.

The representation bits of a floating-point value do not mutate arbitrarily; inparticular, if there is no floating-point operation being performed, NaN signs,quiet bits, and payloads are preserved.

For the purpose of this section,bitcast as well as the following operationsare not “floating-point math operations”:fneg,llvm.fabs, andllvm.copysign. These operations act directly on the underlying bitrepresentation and never change anything except possibly for the sign bit.

Floating-point math operations that return a NaN are an exception from thegeneral principle that LLVM implements IEEE-754 semantics. Unless specifiedotherwise, the following rules apply whenever the IEEE-754 semantics say that aNaN value is returned: the result has a non-deterministic sign; the quiet bitand payload are non-deterministically chosen from the following set of options:

• The quiet bit is set and the payload is all-zero. (“Preferred NaN” case)

• The quiet bit is set and the payload is copied from any input operand that isa NaN. (“Quieting NaN propagation” case)

• The quiet bit and payload are copied from any input operand that is a NaN.(“Unchanged NaN propagation” case)

• The quiet bit is set and the payload is picked from a target-specific set of“extra” possible NaN payloads. The set can depend on the input operand values.This set is empty on x86 and ARM, but can be non-empty on other architectures.(For instance, on wasm, if any input NaN does not have the preferred all-zeropayload or any input NaN is an SNaN, then this set contains all possiblepayloads; otherwise, it is empty. On SPARC, this set consists of the all-onepayload.)

In particular, if all input NaNs are quiet (or if there are no input NaNs), thenthe output NaN is definitely quiet. Signaling NaN outputs can only occur if theyare provided as an input value. For example, “fmul SNaN, 1.0” may be simplifiedto SNaN rather than QNaN. Similarly, if all input NaNs are preferred (or ifthere are no input NaNs) and the target does not have any “extra” NaN payloads,then the output NaN is guaranteed to be preferred.

Floating-point math operations are allowed to treat all NaNs as if they werequiet NaNs. For example, “pow(1.0, SNaN)” may be simplified to 1.0.

Code that requires different behavior than this should use theConstrained Floating-Point Intrinsics.In particular, constrained intrinsics rule out the “Unchanged NaN propagation”case; they are guaranteed to return a QNaN.

Unfortunately, due to hard-or-impossible-to-fix issues, LLVM violates its ownspecification on some architectures:

• x86-32 without SSE2 enabled may convert floating-point values to x86_fp80 andback when performing floating-point math operations; this can lead to resultswith different precision than expected and it can alter NaN values. Sinceoptimizations can make contradicting assumptions, this can lead to arbitrarymiscompilations. Seeissue #44218.

• x86-32 (even with SSE2 enabled) may implicitly perform such a conversion onvalues returned from a function for some calling conventions. Seeissue#66803.

• Older MIPS versions use the opposite polarity for the quiet/signaling bit, andLLVM does not correctly represent this. Seeissue #60796.

Floating-Point Semantics¶

This section defines the semantics for core floating-point operations on typesthat use a format specified by IEEE-745. These types are:half,float,double, andfp128, which correspond to the binary16, binary32, binary64,and binary128 formats, respectively. The “core” operations are those defined insection 5 of IEEE-745, which all have corresponding LLVM operations.

The value returned by those operations matches that of the correspondingIEEE-754 operation executed in thedefault LLVM floating-point environment, except that the behavior of NaN results is insteadasspecified here. In particular, such a floating-point instructionreturning a non-NaN value is guaranteed to always return the same bit-identicalresult on all machines and optimization levels.

This means that optimizations and backends may not change the observed bitwiseresult of these operations in any way (unless NaNs are returned), and frontendscan rely on these operations providing correctly rounded results as described inthe standard.

(Note that this is only about the value returned by these operations; see thefloating-point environment section regarding flags andexceptions.)

Various flags, attributes, and metadata can alter the behavior of theseoperations and thus make them not bit-identical across machines and optimizationlevels any more: most notably, thefast-math flags as well asthestrictfp anddenormal-fp-mathattributes andfpmath metadata <fpmath-metadata>. See theircorresponding documentation for details.

Fast-Math Flags¶

LLVM IR floating-point operations (fneg,fadd,fsub,fmul,fdiv,frem,fcmp,fptrunc,fpext), andphi,select, orcall instructions that return floating-point types may use thefollowing flags to enable otherwise unsafe floating-point transformations.

fast

This flag is a shorthand for specifying all fast-math flags at once, andimparts no additional semantics from using all of them.

nnan

No NaNs - Allow optimizations to assume the arguments and result are notNaN. If an argument is a nan, or the result would be a nan, it producesapoison value instead.

ninf

No Infs - Allow optimizations to assume the arguments and result are not+/-Inf. If an argument is +/-Inf, or the result would be +/-Inf, itproduces apoison value instead.

nsz

No Signed Zeros - Allow optimizations to treat the sign of a zeroargument or zero result as insignificant. This does not imply that -0.0is poison and/or guaranteed to not exist in the operation.

Note: Forphi,select, andcallinstructions, the following return types are considered to be floating-pointtypes:

• Floating-point scalar or vector types

• Array types (nested to any depth) of floating-point scalar or vector types

• Homogeneous literal struct types of floating-point scalar or vector types

definedouble@orig(double%a,double%b,double%c){%t1=fmulcontractreassocdouble%a,%b%val=fmulcontractreassocarcpdouble%t1,%cretdouble%val}definedouble@target(double%a,double%b,double%c){%t1=fmulcontractreassocdouble%b,%c%val=fmulcontractreassocdouble%a,%t1retdouble%val}

Use-list Order Directives¶

Use-list directives encode the in-memory order of each use-list, allowing theorder to be recreated.<order-indexes> is a comma-separated list ofindexes that are assigned to the referenced value’s uses. The referencedvalue’s use-list is immediately sorted by these indexes.

Use-list directives may appear at function scope or global scope. They are notinstructions, and have no effect on the semantics of the IR. When they’re atfunction scope, they must appear after the terminator of the final basic block.

If basic blocks have their address taken viablockaddress() expressions,uselistorder_bb can be used to reorder their use-lists from outside theirfunction’s scope.

Syntax:

uselistorder<ty><value>,{<order-indexes>}uselistorder_bb@function,%block{<order-indexes>}

Examples:

definevoid@foo(i32%arg1,i32%arg2){entry:;...instructions...bb:;...instructions...;Atfunctionscope.uselistorderi32%arg1,{1,0,2}uselistorderlabel%bb,{1,0}};Atglobalscope.uselistorderptr@global,{1,2,0}uselistorderi327,{1,0}uselistorderi32(i32)@bar,{1,0}uselistorder_bb@foo,%bb,{5,1,3,2,0,4}

Source Filename¶

Thesource filename string is set to the original module identifier,which will be the name of the compiled source file when compiling fromsource through the clang front end, for example. It is then preserved throughthe IR and bitcode.

This is currently necessary to generate a consistent unique globalidentifier for local functions used in profile data, which prepends thesource file name to the local function name.

The syntax for the source file name is simply:

source_filename = "/path/to/source.c"

Void Type¶

Overview:

The void type does not represent any value and has no size.

Syntax:

void

Function Type¶

Overview:

The function type can be thought of as a function signature. It consists of areturn type and a list of formal parameter types. The return type of a functiontype is a void type or first class type — except forlabelandmetadata types.

Syntax:

<returntype>(<parameterlist>)

…where ‘<parameterlist>’ is a comma-separated list of typespecifiers. Optionally, the parameter list may include a type..., whichindicates that the function takes a variable number of arguments. Variableargument functions can access their arguments with thevariable argumenthandling intrinsic functions. ‘<returntype>’ is any typeexceptlabel andmetadata.

Examples:

Opaque Structure Types¶

Overview:

Opaque structure types are used to represent structure types thatdo not have a body specified. This corresponds (for example) to the Cnotion of a forward declared structure. They can be named (%X) orunnamed (%52).

It is not possible to create SSA values with an opaque structure type. Inpractice, this largely limits their use to the value type of external globals.

Syntax:

%X=typeopaque%52=typeopaque@g=externalglobal%X

First Class Types¶

Thefirst class types are perhaps the most important.Values of these types are the only ones which can be produced byinstructions.

iN

x86_amx

target("label")target("label",void)target("label",void,i32)target("label",0,1,2)target("label",void,i32,0,1,2)

%val=bitcast<4xi4><i41,i42,i43,i45>toi16; Bitcasting from a vector to an integral type can be seen as; concatenating the values:;   %val now has the hexadecimal value 0x1235.storei16%val,ptr%ptr; In memory the content will be (8-bit addressing):;;    [%ptr + 0]: 00010010  (0x12);    [%ptr + 1]: 00110101  (0x35)

%val=bitcast<4xi4><i41,i42,i43,i45>toi16; Bitcasting from a vector to an integral type can be seen as; concatenating the values:;   %val now has the hexadecimal value 0x5321.storei16%val,ptr%ptr; In memory the content will be (8-bit addressing):;;    [%ptr + 0]: 00100001  (0x21);    [%ptr + 1]: 01010011  (0x53)

<<# elements> x <elementtype> >          ; Fixed-length vector<vscalex<# elements> x <elementtype> > ; Scalable vector

label

token

metadata

[<# elements> x <elementtype>]

%T1=type{<typelist>};Identifiednormalstructtype%T2=type<{<typelist>}>;Identifiedpackedstructtype

Simple Constants¶

Boolean constants

The two strings ‘true’ and ‘false’ are both valid constantsof thei1 type.

Integer constants

Standard integers (such as ‘4’) are constants of theinteger type. They can be either decimal orhexadecimal. Decimal integers can be prefixed with - to representnegative integers, e.g. ‘-1234’. Hexadecimal integers must beprefixed with either u or s to indicate whether they are unsignedor signed respectively. e.g ‘u0x8000’ gives 32768, whilst‘s0x8000’ gives -32768.

Note that hexadecimal integers are sign extended from the numberof active bits, i.e. the bit width minus the number of leadingzeros. So ‘s0x0001’ of type ‘i16’ will be -1, not 1.

Floating-point constants

Floating-point constants use standard decimal notation (e.g.123.421), exponential notation (e.g. 1.23421e+2), or a more precisehexadecimal notation (see below). The assembler requires the exactdecimal value of a floating-point constant. For example, theassembler accepts 1.25 but rejects 1.3 because 1.3 is a repeatingdecimal in binary. Floating-point constants must have afloating-point type.

Null pointer constants

The identifier ‘null’ is recognized as a null pointer constantand must be ofpointer type.

Token constants

The identifier ‘none’ is recognized as an empty token constantand must be oftoken type.

The one non-intuitive notation for constants is the hexadecimal form offloating-point constants. For example, the form‘double   0x432ff973cafa8000’ is equivalent to (but harder to readthan) ‘double4.5e+15’. The only time hexadecimal floating-pointconstants are required (and the only time that they are generated by thedisassembler) is when a floating-point constant must be emitted but itcannot be represented as a decimal floating-point number in a reasonablenumber of digits. For example, NaN’s, infinities, and other specialvalues are represented in their IEEE hexadecimal format so that assemblyand disassembly do not cause any bits to change in the constants.

When using the hexadecimal form, constants of types bfloat, half, float, anddouble are represented using the 16-digit form shown above (which matches theIEEE754 representation for double); bfloat, half and float values must, however,be exactly representable as bfloat, IEEE 754 half, and IEEE 754 singleprecision respectively. Hexadecimal format is always used for long double, andthere are three forms of long double. The 80-bit format used by x86 isrepresented as0xK followed by 20 hexadecimal digits. The 128-bit formatused by PowerPC (two adjacent doubles) is represented by0xM followed by 32hexadecimal digits. The IEEE 128-bit format is represented by0xL followedby 32 hexadecimal digits. Long doubles will only work if they match the longdouble format on your target. The IEEE 16-bit format (half precision) isrepresented by0xH followed by 4 hexadecimal digits. The bfloat 16-bitformat is represented by0xR followed by 4 hexadecimal digits. Allhexadecimal formats are big-endian (sign bit at the left).

There are no constants of type x86_amx.

Complex Constants¶

Complex constants are a (potentially recursive) combination of simpleconstants and smaller complex constants.

Structure constants

Structure constants are represented with notation similar tostructure type definitions (a comma separated list of elements,surrounded by braces ({})). For example:“{i324,float17.0,ptr@G}”, where “@G” is declared as“@G=externalglobali32”. Structure constants must havestructure type, and the number and types of elementsmust match those specified by the type.

Array constants

Array constants are represented with notation similar to array typedefinitions (a comma separated list of elements, surrounded bysquare brackets ([])). For example:“[i3242,i3211,i3274]”. Array constants must havearray type, and the number and types of elements mustmatch those specified by the type. As a special case, character arrayconstants may also be represented as a double-quoted string using thecprefix. For example: “c"HelloWorld\0A\00"”.

Vector constants

Vector constants are represented with notation similar to vectortype definitions (a comma separated list of elements, surrounded byless-than/greater-than’s (<>)). For example:“<i3242,i3211,i3274,i32100>”. Vector constantsmust havevector type, and the number and types ofelements must match those specified by the type.

When creating a vector whose elements have the same constant value, thepreferred syntax issplat(<Ty>Val). For example: “splat(i3211)”.These vector constants must havevector type with anelement type that matches thesplat operand.

Zero initialization

The string ‘zeroinitializer’ can be used to zero initialize avalue to zero ofany type, including scalar andaggregate types. This is often used to avoidhaving to print large zero initializers (e.g. for large arrays) andis always exactly equivalent to using explicit zero initializers.

Metadata node

A metadata node is a constant tuple without types. For example:“!{!0,!{!2,!0},!"test"}”. Metadata can reference constant values,for example: “!{!0,i320,ptr@global,ptr@function,!"str"}”.Unlike other typed constants that are meant to be interpreted as part ofthe instruction stream, metadata is a place to attach additionalinformation such as debug info.

Global Variable and Function Addresses¶

The addresses ofglobal variables andfunctions are always implicitly valid(link-time) constants. These constants are explicitly referenced whentheidentifier for the global is used and always havepointer type. For example, the following is a legal LLVMfile:

@X=globali3217@Y=globali3242@Z=global[2xptr][ptr@X,ptr@Y]

Undefined Values¶

The string ‘undef’ can be used anywhere a constant is expected, andindicates that the user of the value may receive an unspecifiedbit-pattern. Undefined values may be of any type (other than ‘label’or ‘void’) and be used anywhere a constant is permitted.

Undefined values are useful because they indicate to the compiler thatthe program is well defined no matter what value is used. This gives thecompiler more freedom to optimize. Here are some examples of(potentially surprising) transformations that are valid (in pseudo IR):

%A=add%X,undef%B=sub%X,undef%C=xor%X,undefSafe:%A=undef%B=undef%C=undef

This is safe because all of the output bits are affected by the undefbits. Any output bit can have a zero or one depending on the input bits.

%A=or%X,undef%B=and%X,undefSafe:%A=-1%B=0Safe:%A=%X;; By choosing undef as 0%B=%X;; By choosing undef as -1Unsafe:%A=undef%B=undef

These logical operations have bits that are not always affected by theinput. For example, if%X has a zero bit, then the output of the‘and’ operation will always be a zero for that bit, no matter whatthe corresponding bit from the ‘undef’ is. As such, it is unsafe tooptimize or assume that the result of the ‘and’ is ‘undef’.However, it is safe to assume that all bits of the ‘undef’ could be0, and optimize the ‘and’ to 0. Likewise, it is safe to assume thatall the bits of the ‘undef’ operand to the ‘or’ could be set,allowing the ‘or’ to be folded to -1.

%A=selectundef,%X,%Y%B=selectundef,42,%Y%C=select%X,%Y,undefSafe:%A=%X(or%Y)%B=42(or%Y)%C=%Y(if%Yisprovablynotpoison; unsafe otherwise)Unsafe:%A=undef%B=undef%C=undef