LLVM Language Reference Manual

Abstract

This document is a reference manual for the LLVM assembly language. LLVMis a Static Single Assignment (SSA) based representation that providestype safety, low-level operations, flexibility, and the capability ofrepresenting ‘all’ high-level languages cleanly. It is the common coderepresentation used throughout all phases of the LLVM compilationstrategy.

Introduction

The LLVM code representation is designed to be used in three differentforms: as an in-memory compiler IR, as an on-disk bitcode representation(suitable for fast loading by a Just-In-Time compiler), and as a humanreadable assembly language representation. This allows LLVM to provide apowerful intermediate representation for efficient compilertransformations and analysis, while providing a natural means to debugand visualize the transformations. The three different forms of LLVM areall equivalent. This document describes the human readablerepresentation and notation.

The LLVM representation aims to be light-weight and low-level whilebeing expressive, typed, and extensible at the same time. It aims to bea “universal IR” of sorts, by being at a low enough level thathigh-level ideas may be cleanly mapped to it (similar to howmicroprocessors are “universal IR’s”, allowing many source languages tobe mapped to them). By providing type information, LLVM can be used asthe target of optimizations: for example, through pointer analysis, itcan be proven that a C automatic variable is never accessed outside ofthe current function, allowing it to be promoted to a simple SSA valueinstead of a memory location.

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 = add i32 1, %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:

• 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" where xx 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.
• Unnamed values are represented as an unsigned numeric value withtheir prefix. For example, %12, @2, %44.
• Constants, which are described in the section Constants 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 = mul i32 %X, 8

After strength reduction:

%result = shl i32 %X, 3

And the hard way:

%0 = add i32 %X, %X           ; yields i32:%0
%1 = add i32 %0, %0           ; yields i32:%1
%result = add i32 %1, %1

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

• Comments are delimited with a ‘;’ and go until the end of line.
• Unnamed temporaries are created when the result of a computation isnot assigned to a named value.
• Unnamed temporaries are numbered sequentially (using a per-functionincrementing counter, starting with 0). Note that basic blocks and unnamedfunction parameters are included in this numbering. For example, if theentry basic block is not given a label name and all function parameters arenamed, 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.

High Level Structure

Module Structure

LLVM programs are composed of Module’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 = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
 
; External declaration of the puts function
declare i32 @puts(i8* nocapture) nounwind
 
; Definition of main function
define i32 @main() {   ; i32()*
  ; Convert [13 x i8]* to i8*...
  %cast210 = getelementptr [13 x i8], [13 x i8]* @.str, i64 0, i64 0
 
  ; Call puts function to write out the string to stdout.
  call i32 @puts(i8* %cast210)
  ret i32 0
}
 
; Named metadata
!0 = !{i32 42, null, !"string"}
!foo = !{!0}

This example is made up of a global 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 thefollowing linkage 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, an available_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. Globalswith available_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.Unreferenced linkonce globals are allowed to be discarded. Notethat linkonce 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 as linkoncelinkage, except that unreferenced globals with weak 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 “int X;” atglobal scope. Symbols with “common” linkage are merged in thesame way as weak symbols, 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 like llvm.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
• Some languages allow differing globals to be merged, such as twofunctions with different semantics. Other languages, such asC++, ensure that only equivalent globals are ever merged (the“one definition rule” — “ODR”). Such languages can use thelinkonce_odr and weak_odr linkage types to indicate that theglobal will only be merged with equivalent globals. These linkagetypes 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 function declaration to have any linkage typeother than external or extern_weak.

Calling Conventions

LLVM functions, 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 calling convention does notsupport varargs and requires the prototype of all callees to exactlymatch 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.
• “cc 10” - GHC convention

• This calling convention has been implemented specifically for use bythe Glasgow 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 the register pinning performance technique oftenused when implementing functional programming languages. At themoment only X86 supports this convention and it has the followinglimitations:

  • On X86-32 only supports up to 4 bit type parameters. Nofloating-point types are supported.
  • On X86-64 only supports up to 10 bit type parameters and 6floating-point parameters.This calling convention supports tail calloptimization but requires both thecaller and callee are using it.

• “cc 11” - The HiPE calling convention

• This calling convention has been implemented specifically for use bythe High-Performance Erlang(HiPE) compiler, _the_native code compiler of the Ericsson’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 supports tail calloptimization but requires that both thecaller and the callee use it. It uses a _register pinning_mechanism, 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).
• “webkit_jscc” - WebKit’s JavaScript calling convention
• This calling convention has been implemented for WebKit FTL JIT. It passes arguments on thestack right to left (as cdecl does), and returns a value in theplatform’s customary return register.
• “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. See Stack maps and patch points in LLVM.
• “preservemostcc” - The _PreserveMost calling convention

• This calling convention attempts to make the code in the caller asunintrusive as possible. This convention behaves identically to the _C_calling 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. R11 can be used as a scratch register. Floating-point registers(XMMs/YMMs) are not preserved and need to be saved by the caller.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 the cold 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, whereas preserve_mostcc function calls are intended to beon the hot path and definitely executed a lot. Furthermore _preserve_mostcc_doesn’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.

• “preserveallcc” - The _PreserveAll calling convention

• This calling convention attempts to make the code in the caller even lessintrusive than the PreserveMost calling convention. This callingconvention also behaves identical to the C 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).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 the PreserveMost calling convention, will beused by a future version of the ObjectiveC runtime and should be consideredexperimental at this time.

• “cxxfast_tlscc” - The _CXX_FAST_TLS calling convention for access functions
• Clang generates an access function to access C++-style TLS. The accessfunction generally has an entry block, an exit block and an initializationblock that is run at the first time. The entry and exit blocks can accessa few TLS IR variables, each access will be lowered to a platform-specificsequence.

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 the C 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 existing PreserveMost.

• On X86-64 the callee preserves all general purpose registers, except forRDI and RAX.
  • “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.

  • “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. Thiscalling convention does not support varargs and requires the prototype ofall callees to exactly match the prototype of the function definition.
  • “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. 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 with internal or private linkage must have defaultvisibility.

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
• “dllexport” causes the compiler to provide a global pointer to a pointerin a DLL, so that it can be referenced with the dllimport attribute. OnMicrosoft Windows targets, the pointer name is formed by combining_imp and the function or variable name. Since this storage classexists for defining a dll interface, the compiler, assembler and linker knowit is externally referenced and must refrain from deleting the symbol.

Thread Local Storage Models

A variable may be defined as thread_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; see ELF 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 be dso_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 as dso_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. An opaque 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 the datalayout string.Non-integral pointer types represent pointers that have an unspecified bitwiserepresentation; that is, the integral representation may be target dependent orunstable (not backed by a fixed integer).

inttoptr instructions converting integers to non-integral pointer types areill-typed, and so are ptrtoint instructions converting values ofnon-integral pointer types to integers. Vector versions of said instructionsare ill-typed as well.

Global Variables

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

Global variable definitions must be initialized.

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

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 global constant, which indicates thatthe contents of the variable will never 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 marked constant as there is a store to thevariable.

LLVM explicitly allows declarations 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 scope(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 all memory objects in LLVM are accessed throughpointers.

Global variables can be marked with unnamedaddr 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 address _can bemerged with a unnamed_addr constant, the result being a constantwhose address is significant.

If the local_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.

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 with externally_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. The maximum alignment is 1 << 29.

Globals can also have a DLL storage class,an optional runtime preemption specifier,an optional global attributes andan optional list of attached metadata.

Variables and aliases can have aThread Local Storage Model.

Scalable vectors cannot be global variables or members ofstructs or arrays because their size is unknown at compile time.

Syntax:

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

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

@G = addrspace(5) constant float 1.0, section "foo", align 4

The following example just declares a global variable

@G = external global i32

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

@G = thread_local(initialexec) global i32 0, align 4

Functions

LLVM function definitions consist of the “define” keyword, anoptional linkage type, an optional runtime preemptionspecifier, an optional visibilitystyle, an optional DLL storage class,an optional calling convention,an optional unnamed_addr attribute, a return type, an optionalparameter attribute for the return type, a functionname, a (possibly empty) argument list (each with optional parameterattributes), optional function attributes,an optional address space, an optional section, an optional alignment,an optional comdat,an optional garbage collector name, an optional prefix,an optional prologue,an optional personality,an optional list of attached metadata,an opening curly brace, a list of basic blocks, and a closing curly brace.

LLVM function declarations consist of the “declare” keyword, anoptional linkage type, an optional visibility style, an optional DLL storage class, anoptional calling convention, an optional unnamed_addror local_unnamed_addr attribute, an optional address space, a return type,an optional parameter attribute for the return type, a function name, a possiblyempty list of arguments, an optional alignment, an optional garbagecollector name, an optional prefix, and an optionalprologue.

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 instructions,and ends with a terminator 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 any PHI 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 the unnamed_addr attribute is given, the address is known to notbe significant and two identical functions can be merged.

If the local_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 the datalayout string.

Syntax:

define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass]
       [cconv] [ret attrs]
       <ResultType> @<FunctionName> ([argument list])
       [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs]
       [section "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> [parameter Attrs] [name]

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 optional linkage type, an optionalruntime preemption specifier, an optionalvisibility style, an optional DLL storage class and an optional tls model.

Syntax:

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

The linkage must be one of private, internal, linkonce, weak,linkonce_odr, weak_odr, external. Note that some system linkersmight not correctly handle dropping a weak symbol that is aliased.

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

If the local_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.
• No global value in the expression can be a declaration, since thatwould require a relocation, which is not possible.

IFuncs

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

IFuncs have a name and a resolver that is a function called by dynamic linkerthat returns address of another function associated with the name.

IFunc may have an optional linkage type and an optionalvisibility style.

Syntax:

@<Name> = [Linkage] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver>

Comdats

Comdat IR provides access to COFF and ELF object file COMDAT functionality.

Comdats have a name which represents the COMDAT key. All global objects thatspecify this key will only end up in the final object file if the linker choosesthat key over some other key. Aliases are placed in the same COMDAT that theiraliasee computes to, if any.

Comdats have a selection kind to provide input on how the linker shouldchoose between keys in two different object files.

Syntax:

$<Name> = comdat SelectionKind

The selection kind must be one of the following:

• 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.
• noduplicates
• The linker requires that only section with this COMDAT key exist.
• samesize
• The linker may choose any COMDAT key but the sections must contain thesame amount of data.

Note that XCOFF and the Mach-O platform don’t support COMDATs, and ELF andWebAssembly only support any as a selection kind.

Here is an example of a COMDAT group 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
}

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

$foo = comdat any
@foo = global i32 2, comdat

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.

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 = comdat any
$bar = comdat any
@g1 = global i32 42, section "sec", comdat($foo)
@g2 = global i32 42, 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-sections_is supplied to _llc).

Named Metadata

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

• 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 are simple keywords that follow the type specified.If multiple parameter attributes are needed, they are space separated.For example:

declare i32 @printf(i8* noalias nocapture, ...)
declare i32 @atoi(i8 zeroext)
declare signext i8 @returns_signed_char()

Note that any attributes for the function result (nounwind,readonly) come immediately after the argument list.

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).
• 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 or 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 attribute also supports an optional type argument, which must bethe same as the pointee type of the argument.

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.

inalloca

The inalloca argument attribute allows the caller to take theaddress of outgoing stack arguments. An inalloca argument mustbe a pointer to stack memory produced by an alloca instruction.The alloca, or argument allocation, must also be tagged with theinalloca keyword. Only the last argument may have the inallocaattribute, 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. The inalloca attribute cannot beused in conjunction with other attributes that affect argumentstorage, like inreg, nest, sret, or byval. Theinalloca attribute also disables LLVM’s implicit lowering oflarge aggregate return values, which means that frontend authorsmust lower them with sret 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 with llvm.stackrestore.

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

• sret
• 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. This is not a valid attributefor return values.

• align <n>
• This indicates that the pointer value may be assumed by the optimizer tohave the specified alignment. If the pointer value does not have thespecified alignment, behavior is undefined.

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

• noalias
• This indicates that objects 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. The attribute on a return valuealso has additional semantics described below. The caller shares theresponsibility with the callee for ensuring that these requirements are met.For further details, please see the discussion of the NoAlias response inalias analysis.

Note that this definition of noalias is intentionally similarto the definition of restrict in C99 for function arguments.

For function return values, C99’s restrict is not meaningful,while LLVM’s noalias is. Furthermore, the semantics of the noaliasattribute on return values are stronger than the semantics of the attributewhen used on function arguments. On function return values, the noaliasattribute 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.

• nocapture
• This indicates that the callee does not make any copies of thepointer that outlive the callee itself. This is not a validattribute for return values. Addresses used in volatile operationsare considered to be captured.
• 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,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. The nonnull attribute does not implydereferenceability (consider a pointer to one element past the end of anarray), however dereferenceable(<n>) does imply nonnull inaddrspace(0) (which is the default address space).
• 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>) are dereferenceable(<n>).For address space 0 dereferenceable_or_null(<n>) implies thata pointer is exactly one of dereferenceable(<n>) or null,and in other address spaces dereferenceable_or_null(<n>)implies that a pointer is at least one of dereferenceable(<n>)or null (i.e. it may be both null 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.
• 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 a swifterror parameter has to come from a swifterror alloca orthe swifterror parameter of the caller. A swifterror value (eitherthe parameter or the alloca) can only be loaded and stored from, or used asa swifterror 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 the swifterror attributeon a parameter is not ABI-compatible with one which does not.

These constraints also allow LLVM to assume that a swifterror 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.

Garbage Collector Strategy Names

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

define void @f() gc "name" { ... }

The supported values of name includes those built 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 single i32,

define void @f() prefix i32 123 { ... }

The prefix data can be referenced as,

%0 = bitcast void* () @f to i32*
%a = getelementptr inbounds i32, i32* %0, i32 -1
%b = load i32, i32* %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 the available_externally linkage in that the data may be used by theoptimizers but will not be emitted in the object file.

Prologue Data

The prologue 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 is i8 144,which encodes the nop 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 encode jmp .+10:

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

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

Personality Function

The personality 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 = { alwaysinline alignstack=4 }
 
; Target-dependent attributes:
attributes #1 = { "no-sse" }
 
; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".
define void @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 that follow the type specified.If multiple attributes are needed, they are space separated. Forexample:

define void @f() noinline { ... }
define void @f() alwaysinline { ... }
define void @f() alwaysinline optsize { ... }
define void @f() optsize { ... }

• 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.
• 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 atleast CallSite.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 the nobuiltin attribute. This is only valid at call sites fordirect calls to functions that are declared with the nobuiltinattribute.
• 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
• In some parallel execution models, there exist operations that cannot bemade control-dependent on any additional values. We call such operationsconvergent, and mark them with this attribute.

The convergent attribute may appear on functions or call/invokeinstructions. When it appears on a function, it indicates that calls tothis function should not be made control-dependent on additional values.For example, the intrinsic llvm.nvvm.barrier0 is convergent, socalls to this intrinsic cannot be made control-dependent on additionalvalues.

When it appears on a call/invoke, the convergent attribute indicatesthat we should treat the call as though we’re calling a convergentfunction. This is particularly useful on indirect calls; without this wemay treat such calls as though the target is non-convergent.

The optimizer may remove the convergent attribute on functions when itcan prove that the function does not execute any convergent operations.Similarly, the optimizer may remove convergent on calls/invokes when itcan prove that the call/invoke cannot call a convergent function.

• inaccessiblememonly
• This attribute indicates that the function may only access memory thatis not accessible by the module being compiled. This is a weaker formof readnone. If the function reads or writes other memory, thebehavior is undefined.
• inaccessiblemem_or_argmemonly
• This attribute indicates that the function may only access memory that iseither not accessible by the module being compiled, or is pointed toby its pointer arguments. This is a weaker form of argmemonly. If thefunction reads or writes other memory, the behavior is undefined.
• 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 be unnamed_addr.
• 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.
• naked
• This attribute disables prologue / epilogue emission for thefunction. This can have very system-specific consequences.
• "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 the builtin attribute. This is valid at call sitesand on function declarations and definitions.
• noduplicate
• This attribute indicates that calls to the function cannot beduplicated. A call to a noduplicate function may be movedwithin its parent function, but may not be duplicated withinits parent function.

A function containing a noduplicate 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 orindirectly, call a memory-deallocation function (free, for example). As aresult, uncaptured pointers that are known to be dereferenceable prior to acall to a function with the nofree attribute are still known to bedereferenceable after the call (the capturing condition is necessary inenvironments where the function might communicate the pointer to another threadwhich then deallocates the memory).
• noimplicitfloat
• This attributes disables implicit floating-point instructions.
• noinline
• This attribute indicates that the inliner should never inline thisfunction in any situation. This attribute may not be used togetherwith the alwaysinline attribute.
• 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.
• 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 of atomic accessesthat enforce an order, thus not “unordered” and “monotonic”, volatile accesses,as well as convergent function calls. Note that through convergent function callsnon-memory communication, e.g., cross-lane operations, are possible and are alsoconsidered synchronization. However convergent does not contradict nosync.If an annotated 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.
• "null-pointer-is-valid"
• If "null-pointer-is-valid" is set to "true", then null addressin address-space 0 is considered to be a valid address for memory loads andstores. Any analysis or optimization should not treat dereferencing apointer to null as undefined behavior in this function.Note: Comparing address of a global variable to null may stillevaluate to false because of a limitation in querying this attribute insideconstant expressions.
• 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 the alwaysinlineattribute; this attribute is also incompatiblewith the minsize attribute and the optsize attribute.

This attribute requires the noinline attribute to be specified onthe function as well, so the function is never inlined into any caller.Only functions with the alwaysinline 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.
• "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.

• readnone
• On a function, this attribute indicates that the function computes itsresult (or decides to unwind an exception) based strictly on its arguments,without dereferencing any pointer arguments or otherwise accessingany mutable state (e.g. memory, control registers, etc) visible tocaller functions. It does not write through any pointer arguments(including byval arguments) and never changes any state visibleto callers. This means while it cannot unwind exceptions by callingthe C++ exception throwing methods (since they write to memory), there maybe non-C++ mechanisms that throw exceptions without writing to LLVMvisible memory.

On an argument, this attribute indicates that the function does notdereference that pointer argument, even though it may read or write thememory that the pointer points to if accessed through other pointers.

If a readnone function reads or writes memory visible to the program, orhas other side-effects, the behavior is undefined. If a function reads fromor writes to a readnone pointer argument, the behavior is undefined.

• readonly
• On a function, this attribute indicates that the function does not writethrough any pointer arguments (including byval arguments) or otherwisemodify any state (e.g. memory, control registers, etc) visible tocaller functions. It may dereference pointer arguments and readstate that may be set in the caller. A readonly function alwaysreturns the same value (or unwinds an exception identically) whencalled with the same set of arguments and global state. This means while itcannot unwind exceptions by calling the C++ exception throwing methods(since they write to memory), there may be non-C++ mechanisms that throwexceptions without writing to LLVM visible memory.

On an argument, this attribute indicates that the function does not writethrough this pointer argument, even though it may write to the memory thatthe pointer points to.

If a readonly function writes memory visible to the program, orhas other side-effects, the behavior is undefined. If a function writes toa readonly pointer argument, the behavior is undefined.

• "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.
• writeonly
• On a function, this attribute indicates that the function may write to butdoes not read from memory.

On an argument, this attribute indicates that the function may write to butdoes not read through this pointer argument (even though it may read fromthe memory that the pointer points to).

If a writeonly function reads memory visible to the program, orhas other side-effects, the behavior is undefined. If a function readsfrom a writeonly pointer argument, the behavior is undefined.

• argmemonly
• This attribute indicates that the only memory accesses inside function areloads and stores from objects pointed to by its pointer-typed arguments,with arbitrary offsets. Or in other words, all memory operations in thefunction can refer to memory only using pointers based on its functionarguments.

Note that argmemonly can be used together with readonly attributein order to specify that function reads only from its arguments.

If an argmemonly function reads or writes memory other than the pointerarguments, or has other side-effects, the behavior is undefined.

• 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 a safestack attribute is inlined into afunction that doesn’t have a safestack attribute or which has anssp, sspstrong or sspreq attribute, then the resultingfunction will have a safestack 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.
• 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 that speculatable 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 than ssp-buffer-size (default 8).
  • Aggregates containing character arrays larger than ssp-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 that has an ssp attribute is inlined into afunction that doesn’t have an ssp attribute, then the resultingfunction will have an ssp attribute.

• sspreq
• This attribute indicates that the function should always emit astack smashing protector. This overrides the ssp functionattribute.

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:

• Large arrays and structures containing large arrays(>= ssp-buffer-size) are closest to the stack protector.
• Small arrays and structures containing small arrays(< ssp-buffer-size) are 2nd closest to the protector.
• Variables that have had their address taken are 3rd closest to theprotector.If a function that has an sspreq attribute is inlined into afunction that doesn’t have an sspreq attribute or which has anssp or sspstrong attribute, then the resulting function will havean sspreq attribute.

• 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:

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

  • Small arrays and structures containing small arrays(< ssp-buffer-size) are 2nd closest to the protector.
  • Variables that have had their address taken are 3rd closest to theprotector.This overrides the ssp function attribute.

If a function that has an sspstrong attribute is inlined into afunction that doesn’t have an sspstrong attribute, then theresulting function will have an sspstrong attribute.

• 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", or "positive-zero". The first entryindicates the flushing mode for the result of floating pointoperations. The second indicates the handling of denormal inputsto floating point instructions. For compatability 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. While this indicates theexpected floating point mode the function will be executed with,this does not make any attempt to ensure the mode isconsistent. User or platform code is expected to set the floatingpoint mode appropriately before function entry.

If the input mode is "preserve-sign", or "positive-zero", afloating-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
• 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.
• 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 eiplog. It iscurrently x86_64-specific.

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 a call to listthe vector functions associated to the function. Notice that theattribute cannot be attached to a invoke 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<scalarname> 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 of declarevariant 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 at https://github.com/ARM-software/abi-aa andhttps://software.intel.com/en-us/articles/vector-simd-function-abi,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  -> X86 SSE, AVX, AVX2, AVX512
      | n | s          -> Armv8 Advanced SIMD, SVE
      | __LLVM__       -> Internal LLVM Vector ISA

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

<mask>:= M | N         -> mask | no mask
 
<vlen>:= number        -> number of lanes
       | x             -> VLA (Vector Length Agnostic)
 
<parameters>:= v              -> vector
             | l | l <number> -> linear
             | R | R <number> -> linear with ref modifier
             | L | L <number> -> linear with val modifier
             | U | U <number> -> linear with uval modifier
             | ls <pos>       -> runtime linear
             | Rs <pos>       -> runtime linear with ref modifier
             | Ls <pos>       -> runtime linear with val modifier
             | Us <pos>       -> runtime linear with uval modifier
             | u              -> uniform
 
<scalar_name>:= name of the scalar function
 
<vector_redirection>:= optional, custom name of the vector function

Global Attributes

Attributes may be set to communicate additional information about a global variable.Unlike function attributes, attributes on a global variableare grouped into a single attribute group.

Operand Bundles

Operand bundles are tagged sets of SSA values that can be associatedwith certain LLVM instructions (currently only call s andinvoke s). In a way they are like metadata, but dropping them isincorrect and will change program semantics.

Syntax:

operand bundle set ::= '[' operand bundle (, operand bundle )* ']'
operand bundle ::= tag '(' [ bundle operand ] (, bundle operand )* ')'
bundle operand ::= SSA value
tag ::= string constant

Operand bundles are not 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 the call (or invoke), 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 isreadnone or readonly), 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.

Deoptimization Operand Bundles

Deoptimization operand bundles are characterized by the "deopt"operand bundle tag. These operand bundles represent an alternate“safe” continuation for the call site they’re attached to, and can beused by a suitable runtime to deoptimize the compiled frame at thespecified call site. There can be at most one "deopt" operandbundle attached to a call site. Exact details of deoptimization isout of scope for the language reference, but it usually involvesrewriting a compiled frame into a set of interpreted frames.

From the compiler’s perspective, deoptimization operand bundles makethe call sites they’re attached to at least readonly. They readthrough all of their pointer typed operands (even if they’re nototherwise escaped) and the entire visible heap. Deoptimizationoperand bundles do not capture their operands except duringdeoptimization, in which case control will not be returned to thecompiled frame.

The inliner knows how to inline through calls that have deoptimizationoperand bundles. Just like inlining through a normal call siteinvolves composing the normal and exceptional continuations, inliningthrough a call site with a deoptimization operand bundle needs toappropriately compose the “safe” deoptimization continuation. Theinliner does this by prepending the parent’s deoptimizationcontinuation to every deoptimization continuation in the inlined body.E.g. inlining @f into @g in the following example

define void @f() {
  call void @x()  ;; no deopt state
  call void @y() [ "deopt"(i32 10) ]
  call void @y() [ "deopt"(i32 10), "unknown"(i8* null) ]
  ret void
}
 
define void @g() {
  call void @f() [ "deopt"(i32 20) ]
  ret void
}

will result in

define void @g() {
  call void @x()  ;; still no deopt state
  call void @y() [ "deopt"(i32 20, i32 10) ]
  call void @y() [ "deopt"(i32 20, i32 10), "unknown"(i8* null) ]
  ret void
}

It is the frontend’s responsibility to structure or encode thedeoptimization state in a way that syntactically prepending thecaller’s deoptimization state to the callee’s deoptimization state issemantically equivalent to composing the caller’s deoptimizationcontinuation after the callee’s deoptimization continuation.

Funclet Operand Bundles

Funclet operand bundles are characterized by the "funclet"operand bundle tag. These operand bundles indicate that a call siteis within a particular funclet. There can be at most one"funclet" operand bundle attached to a call site and it must haveexactly one bundle operand.

If any funclet EH pads have been “entered” but not “exited” (per thedescription in the EH doc),it is undefined behavior to execute a call or invoke which:

• does not have a "funclet" bundle and is not a call to a nounwindintrinsic, or
• has a "funclet" bundle whose operand is not the most-recently-enterednot-yet-exited funclet EH pad.

Similarly, if no funclet EH pads have been entered-but-not-yet-exited,executing a call or invoke with a "funclet" bundle is undefined behavior.

GC Transition Operand Bundles

GC transition operand bundles are characterized by the"gc-transition" operand bundle tag. These operand bundles mark acall as a transition between a function with one GC strategy to afunction with a different GC strategy. If coordinating the transitionbetween GC strategies requires additional code generation at the callsite, these bundles may contain any values that are needed by thegenerated code. For more details, see GC Transitions.

Assume Operand Bundles

Operand bundles on an llvm.assume allows representingassumptions that a parameter attribute or afunction attribute holds for a certain value at a certainlocation. Operand bundles enable assumptions that are either hard or impossibleto represent as a boolean argument of an llvm.assume.

An assume operand bundle has the form:

"<tag>"([ <holds for value> [, <attribute argument>] ])

• The tag of the operand bundle is usually the name of attribute that can beassumed to hold. It can also be ignore, this tag doesn’t contain anyinformation and should be ignored.
• The first argument if present is the value for which the attribute hold.
• The second argument if present is an argument of the attribute.

If there are no arguments the attribute is a property of the call location.

If the represented attribute expects a constant argument, the argument providedto the operand bundle should be a constant as well.

For example:

call void @llvm.assume(i1 true) ["align"(i32* %val, i32 8)]

allows the optimizer to assume that at location of call tollvm.assume %val has an alignment of at least 8.

call void @llvm.assume(i1 %cond) ["cold"(), "nonnull"(i64* %val)]

allows the optimizer to assume that the llvm.assumecall location is cold and that %val may not be null.

Just like for the argument of llvm.assume, if any of theprovided guarantees are are violated at runtime the behavior is undefined.

Even if the assumed property can be encoded as a boolean value, likenonnull, using operand bundles to express the property can still havebenefits:

• Attributes that can be expressed via operand bundles are directly theproperty that the optimizer uses and cares about. Encoding attributes asoperand bundles removes the need for an instruction sequence that representsthe property (e.g., icmp ne i32* %p, null for nonnull) and for theoptimizer to deduce the property from that instruction sequence.
• Expressing the property using operand bundles makes it easy to identify theuse of the value as a use in an llvm.assume. This thensimplifies and improves heuristics, e.g., for use “use-sensitive”optimizations.

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:

module asm "inline asm code goes here"
module asm "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 string must 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:

target datalayout = "layout specification"

The layout 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. The stack alignmentmust be a multiple of 8-bits. If omitted, the natural stackalignment defaults to “unspecified”, which does not prevent anyalignment promotions.
• P<address space>
• 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.
• A<address space>
• 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 size of a pointer and its <abi> and<pref>erred alignments for address space n. The fourth parameter<idx> is a size of index that used for address calculation. If notspecified, the default index size is equal to the pointer size. All sizesare in bits. The address space, n, is optional, and if not specified,denotes the default address space 0. The value of n must bein the range [1,2^23).
• 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^23).
• v<size>:<abi>:<pref>
• This specifies the alignment for a vector type of a given bit<size>.
• 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.
• a:<abi>:<pref>
• This specifies the alignment for an object of aggregate type.
• 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.
  • m: Mips mangling: Private symbols get a $ prefix.
  • o: Mach-O mangling: Private symbols get L 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 to x, except that normal Csymbols do not receive a _ prefix.
• n<size1>:<size2>:<size3>…
• This specifies a set of native integer widths for the target CPU inbits. For example, it might contain n32 for 32-bit PowerPC,n32:64 for PowerPC 64, or n8:16:32:64 for X86-64. Elements ofthis set are considered to support most general arithmetic operationsefficiently.
• ni:<address space0>:<address space1>:<address space2>…
• This specifies pointer types with the specified address spacesas Non-Integral Pointer Type s. The 0address space cannot be specified as non-integral.

On every specification that takes a <abi>:<pref>, specifying the<pref> alignment is optional. If omitted, the preceding :should be omitted too and <pref> will be equal to <abi>.

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

• E - big 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
• 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:

• If the type sought is an exact match for one of the specifications,that specification is used.
• 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).
• If no match is found, and the type sought is a vector type, then thelargest vector type that is smaller than the sought vector type willbe used as a fall back. This happens because <128 x double> can beimplemented in terms of 64 <2 x double>, for example.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 ultimate code 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:

target triple = "x86_64-apple-macosx10.7.0"

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

ARCHITECTURE-VENDOR-OPERATING_SYSTEM
ARCHITECTURE-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.

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 is based 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.
• An undef value in any 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 is based on another pointer value according to thefollowing rules:

• A pointer value formed from a scalar getelementptr operation is based onthe pointer-typed operand of the getelementptr.
• The pointer in lane l of the result of a vector getelementptr operationis based on the pointer in lane l of the vector-of-pointers-typed operandof the getelementptr.
• The result value of a bitcast is based on the operand of thebitcast.
• A pointer value formed by an inttoptr is based 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 a store 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.

Volatile Memory Accesses

Certain memory accesses, such as load’s,store’s, and llvm.memcpy’s may bemarked volatile. The optimizers must not change the number ofvolatile operations or change their order of execution relative to othervolatile operations. The optimizers may 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.

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.

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.

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.

Rationale

Platforms may rely on volatile loads and stores of natively supporteddata width to be executed as single instruction. For example, in Cthis holds for an l-value of volatile primitive type with nativehardware support, but not necessarily for aggregate types. Thefrontend upholds these expectations, which are intentionallyunspecified in the IR. The rules above ensure that IR transformationsdo not violate the frontend’s contract with the language.

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++0x memory model.

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

We define a happens-before partial order as the least partial orderthat

• Is a superset of single-thread program order, and
• When a synchronizes-with b, includes an edge from a tob. Synchronizes-with pairs are introduced by platform-specifictechniques, like pthread locks, thread creation, thread joining,etc., and by atomic instructions. (See also Atomic Memory OrderingConstraints).

Note that program order does not introduce happens-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 write1 happens before write2, andwrite2 happens before Rbyte, thenRbyte does not see write1.
• If Rbyte happens before write3, thenRbyte does not see write3.

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 support sig_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 beforeRbyte, Rbyte returns undef for that byte.
• Otherwise, if Rbyte may see exactly one write,Rbyte returns the value written by that write.
• Otherwise, if R is atomic, and all the writes Rbyte maysee are atomic, it chooses one of the values written. See the AtomicMemory Ordering Constraints section for additionalconstraints on how the choice is made.
• Otherwise Rbyte returns undef.

R returns the value composed of the series of bytes it read. Thisimplies that some bytes within the value may be undef withoutthe entire value being undef. 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, and atomic store) takeordering parameters that determine which other atomic instructions onthe same address they synchronize with. These semantics are borrowedfrom Java and C++0x, but are somewhat more colloquial. If thesedescriptions aren’t precise enough, check those specs (see specreferences in the atomics guide).fence instructions treat these orderings somewhatdifferently since they don’t take an address. See that instruction’sdocumentation 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 of unordered, there is a singletotal order for modifications by monotonic 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 of monotonic (orstronger) operations on the same address. If an address is writtenmonotonic-ally by one thread, and other threads monotonic-allyread that address repeatedly, the other threads must eventually seethe write. This corresponds to the C++0x/C1xmemory_order_relaxed.
• acquire
• In addition to the guarantees of monotonic, asynchronizes-with edge may be formed with a release operation.This is intended to model C++’s memory_order_acquire.
• release
• In addition to the guarantees of monotonic, if this operationwrites a value which is subsequently read by an acquireoperation, it synchronizes-with that operation. (This isn’t acomplete description; see the C++0x definition of a releasesequence.) This corresponds to the C++0x/C1xmemory_order_release.
• acq_rel (acquire+release)
• Acts as both an acquire and release operation on itsaddress. This corresponds to the C++0x/C1x memory_order_acq_rel.
• seq_cst (sequentially consistent)
• In addition to the guarantees of acqrel (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, which isconsistent with the _happens-before partial order and with themodification orders of all the affected addresses. Eachsequentially-consistent read sees the last preceding write to thesame address in this global order. This corresponds to the C++0x/C1xmemory_order_seq_cst and Java volatile.

If an atomic operation is marked syncscope("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 marked syncscope("<target-scope>"), where<target-scope> is a target specific synchronization scope, then it is targetdependent if it synchronizes with and participates in the seq_cst totalorderings of other operations.

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

Floating-Point Environment

The default LLVM floating-point environment assumes that floating-pointinstructions do not have side effects. Results assume the round-to-nearestrounding mode. No floating-point exception state is maintained in thisenvironment. Therefore, there is no attempt to create or preserve invalidoperation (SNaN) or division-by-zero exceptions.

The benefit of this exception-free assumption is that floating-pointoperations may be speculated freely without any other fast-math relaxationsto the floating-point model.

Code that requires different behavior than this should use theConstrained Floating-Point Intrinsics.

Fast-Math Flags

LLVM IR floating-point operations (fneg, fadd,fsub, fmul, fdiv,frem, fcmp), phi,select and callmay use the following flags to enable otherwise unsafefloating-point transformations.

• 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 producesa poison 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 a poison value instead.
• nsz
• No Signed Zeros - Allow optimizations to treat the sign of a zeroargument or result as insignificant.
• arcp
• Allow Reciprocal - Allow optimizations to use the reciprocal of anargument rather than perform division.
• contract
• Allow floating-point contraction (e.g. fusing a multiply followed by anaddition into a fused multiply-and-add).
• afn
• Approximate functions - Allow substitution of approximate calculations forfunctions (sin, log, sqrt, etc). See floating-point intrinsic definitionsfor places where this can apply to LLVM’s intrinsic math functions.
• reassoc
• Allow reassociation transformations for floating-point instructions.This may dramatically change results in floating-point.
• fast
• This flag implies all of the others.

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 via blockaddress() expressions,uselistorder_bb can be used to reorder their use-lists from outside theirfunction’s scope.

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

define void @foo(i32 %arg1, i32 %arg2) {
entry:
  ; ... instructions ...
bb:
  ; ... instructions ...
 
  ; At function scope.
  uselistorder i32 %arg1, { 1, 0, 2 }
  uselistorder label %bb, { 1, 0 }
}
 
; At global scope.
uselistorder i32* @global, { 1, 2, 0 }
uselistorder i32 7, { 1, 0 }
uselistorder i32 (i32) @bar, { 1, 0 }
uselistorder_bb @foo, %bb, { 5, 1, 3, 2, 0, 4 }

Source Filename

The source 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"

Type System

The LLVM type system is one of the most important features of theintermediate representation. Being typed enables a number ofoptimizations to be performed on the intermediate representationdirectly, without having to do extra analyses on the side before thetransformation. A strong type system makes it easier to read thegenerated code and enables novel analyses and transformations that arenot feasible to perform on normal three address code representations.

Void Type

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

void

Function Type

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 for labeland metadata types.

<returntype> (<parameter list>)

…where ‘<parameter list>’ 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 the variable argumenthandling intrinsic functions. ‘<returntype>’ is any typeexcept label and metadata.

First Class Types

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

Single Value Types

These are the types that are valid in registers from CodeGen’s perspective.

Integer Type

The integer type is a very simple type that simply specifies anarbitrary bit width for the integer type desired. Any bit width from 1bit to 2²³-1 (about 8 million) can be specified.

iN

The number of bits the integer will occupy is specified by the Nvalue.

Examples:

Floating-Point Types

The binary format of half, float, double, and fp128 correspond to theIEEE-754-2008 specifications for binary16, binary32, binary64, and binary128respectively.

X86_mmx Type

The x86_mmx type represents a value held in an MMX register on an x86machine. The operations allowed on it are quite limited: parameters andreturn values, load and store, and bitcast. User-specified MMXinstructions are represented as intrinsic or asm calls with argumentsand/or results of this type. There are no arrays, vectors or constantsof this type.

x86_mmx

Pointer Type

The pointer type is used to specify memory locations. Pointers arecommonly used to reference objects in memory.

Pointer types may have an optional address space attribute defining thenumbered address space where the pointed-to object resides. The defaultaddress space is number zero. The semantics of non-zero address spacesare target-specific.

Note that LLVM does not permit pointers to void (void) nor does itpermit pointers to labels (label). Use i8* instead.

<type> *

Vector Type

A vector type is a simple derived type that represents a vector ofelements. Vector types are used when multiple primitive data areoperated in parallel using a single instruction (SIMD). A vector typerequires a size (number of elements), an underlying primitive data type,and a scalable property to represent vectors where the exact hardwarevector length is unknown at compile time. Vector types are consideredfirst class.

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

The number of elements is a constant integer value larger than 0;elementtype may be any integer, floating-point or pointer type. Vectorsof size zero are not allowed. For scalable vectors, the total number ofelements is a constant multiple (called vscale) of the specified numberof elements; vscale is a positive integer that is unknown at compile timeand the same hardware-dependent constant for all scalable vectors at runtime. The size of a specific scalable vector type is thus constant withinIR, even if the exact size in bytes cannot be determined until run time.

Label Type

The label type represents code labels.

label

Token Type

The token type is used when a value is associated with an instructionbut all uses of the value must not attempt to introspect or obscure it.As such, it is not appropriate to have a phi orselect of type token.

token

Metadata Type

The metadata type represents embedded metadata. No derived types may becreated from metadata except for function arguments.

metadata

Aggregate Types

Aggregate Types are a subset of derived types that can contain multiplemember types. Arrays and structs areaggregate types. Vectors are not considered to beaggregate types.

Array Type

The array type is a very simple derived type that arranges elementssequentially in memory. The array type requires a size (number ofelements) and an underlying data type.

[<# elements> x <elementtype>]

The number of elements is a constant integer value; elementtype maybe any type with a size.

Here are some examples of multidimensional arrays:

There is no restriction on indexing beyond the end of the array impliedby a static type (though there are restrictions on indexing beyond thebounds of an allocated object in some cases). This means thatsingle-dimension ‘variable sized array’ addressing can be implemented inLLVM with a zero length array type. An implementation of ‘pascal stylearrays’ in LLVM could use the type “{ i32, [0 x float]}”, forexample.

Structure Type

The structure type is used to represent a collection of data memberstogether in memory. The elements of a structure may be any type that hasa size.

Structures in memory are accessed using ‘load’ and ‘store’ bygetting a pointer to a field with the ‘getelementptr’ instruction.Structures in registers are accessed using the ‘extractvalue’ and‘insertvalue’ instructions.

Structures may optionally be “packed” structures, which indicate thatthe alignment of the struct is one byte, and that there is no paddingbetween the elements. In non-packed structs, padding between field typesis inserted as defined by the DataLayout string in the module, which isrequired to match what the underlying code generator expects.

Structures can either be “literal” or “identified”. A literal structureis defined inline with other types (e.g. {i32, i32}*) whereasidentified types are always defined at the top level with a name.Literal types are uniqued by their contents and can never be recursiveor opaque since there is no way to write one. Identified types can berecursive, can be opaqued, and are never uniqued.

%T1 = type { <type list> }     ; Identified normal struct type
%T2 = type <{ <type list> }>   ; Identified packed struct type

Opaque Structure Types

Opaque structure types are used to represent named structure types thatdo not have a body specified. This corresponds (for example) to the Cnotion of a forward declared structure.

%X = type opaque
%52 = type opaque

Constants

LLVM has several different basic types of constants. This sectiondescribes them all and their syntax.

Simple Constants

• Boolean constants
• The two strings ‘true’ and ‘false’ are both valid constantsof the i1 type.
• Integer constants
• Standard integers (such as ‘4’) are constants of theinteger type. Negative numbers may be used withinteger types.
• 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 of pointer type.
• Token constants
• The identifier ‘none’ is recognized as an empty token constantand must be of token 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) ‘double 4.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 half, float, anddouble are represented using the 16-digit form shown above (whichmatches the IEEE754 representation for double); half and float valuesmust, however, be exactly representable as IEEE 754 half and singleprecision, respectively. Hexadecimal format is always used for longdouble, and there are three forms of long double. The 80-bit format usedby x86 is represented as 0xK followed by 20 hexadecimal digits. The128-bit format used by PowerPC (two adjacent doubles) is represented by0xM followed by 32 hexadecimal digits. The IEEE 128-bit format isrepresented by 0xL followed by 32 hexadecimal digits. Long doubleswill only work if they match the long double format on your target.The IEEE 16-bit format (half precision) is represented by 0xHfollowed by 4 hexadecimal digits. All hexadecimal formats are big-endian(sign bit at the left).

There are no constants of type x86_mmx.

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:“{ i32 4, float 17.0, i32* @G }”, where “@G” is declared as“@G = external global i32”. 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:“[ i32 42, i32 11, i32 74 ]”. 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 the cprefix. For example: “c"Hello World\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:“< i32 42, i32 11, i32 74, i32 100 >”. Vector constantsmust have vector type, and the number and types ofelements must match those specified by the type.
• Zero initialization
• The string ‘zeroinitializer’ can be used to zero initialize avalue to zero of any 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, i32 0, i8 @global, i64 (i64) @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 of global variables andfunctions are always implicitly valid(link-time) constants. These constants are explicitly referenced whenthe identifier for the global is used and always havepointer type. For example, the following is a legal LLVMfile:

@X = global i32 17@Y = global i32 42@Z = global [2 x i32] [ i32 @X, i32* @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, undef
Safe:
  %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, undef
Safe:
  %A = -1
  %B = 0
Safe:
  %A = %X  ;; By choosing undef as 0
  %B = %X  ;; By choosing undef as -1
Unsafe:
  %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 = select undef, %X, %Y
  %B = select undef, 42, %Y
  %C = select %X, %Y, undef
Safe:
  %A = %X     (or %Y)
  %B = 42     (or %Y)
  %C = %Y
Unsafe:
  %A = undef
  %B = undef
  %C = undef

This set of examples shows that undefined ‘select’ (and conditionalbranch) conditions can go either way, but they have to come from oneof the two operands. In the %A example, if %X and %Y wereboth known to have a clear low bit, then %A would have to have acleared low bit. However, in the %C example, the optimizer isallowed to assume that the ‘undef’ operand could be the same as%Y, allowing the whole ‘select’ to be eliminated.

  %A = xor undef, undef

  %B = undef
  %C = xor %B, %B

  %D = undef
  %E = icmp slt %D, 4
  %F = icmp gte %D, 4

Safe:
  %A = undef
  %B = undef
  %C = undef
  %D = undef
  %E = undef
  %F = undef

This example points out that two ‘undef’ operands are notnecessarily the same. This can be surprising to people (and also matchesC semantics) where they assume that “X^X” is always zero, even ifX is undefined. This isn’t true for a number of reasons, but theshort answer is that an ‘undef’ “variable” can arbitrarily changeits value over its “live range”. This is true because the variabledoesn’t actually have a live range. Instead, the value is logicallyread from arbitrary registers that happen to be around when needed, sothe value is not necessarily consistent over time. In fact, %A and%C need to have the same semantics or the core LLVM “replace alluses with” concept would not hold.

To ensure all uses of a given register observe the same value (even if‘undef’), the freeze instruction can be used.

  %A = sdiv undef, %X
  %B = sdiv %X, undef
Safe:
  %A = 0
b: unreachable

These examples show the crucial difference between an undefined value_and _undefined behavior. An undefined value (like ‘undef’) isallowed to have an arbitrary bit-pattern. This means that the %Aoperation can be constant folded to ‘0’, because the ‘undef’could be zero, and zero divided by any value is zero.However, in the second example, we can make a more aggressiveassumption: because the undef is allowed to be an arbitrary value,we are allowed to assume that it could be zero. Since a divide by zerohas undefined behavior, we are allowed to assume that the operationdoes not execute at all. This allows us to delete the divide and allcode after it. Because the undefined operation “can’t happen”, theoptimizer can assume that it occurs in dead code.

a:  store undef -> %X
b:  store %X -> undef
Safe:
a: <deleted>
b: unreachable

A store of an undefined value can be assumed to not have any effect;we can assume that the value is overwritten with bits that happen tomatch what was already there. However, a store to an undefinedlocation could clobber arbitrary memory, therefore, it has undefinedbehavior.

MemorySanitizer, a detector of uses of uninitialized memory,defines a branch with condition that depends on an undef value (orcertain other values, like e.g. a result of a load from heap-allocatedmemory that has never been stored to) to have an externally visibleside effect. For this reason functions with _sanitize_memory_attribute are not allowed to produce such branches “out of thinair”. More strictly, an optimization that inserts a conditional branchis only valid if in all executions where the branch condition has atleast one undefined bit, the same branch condition is evaluated in theinput IR as well.

Poison Values

In order to facilitate speculative execution, many instructions do notinvoke immediate undefined behavior when provided with illegal operands,and return a poison value instead.

There is currently no way of representing a poison value in the IR; theyonly exist when produced by operations such as add withthe nsw flag.

Poison value behavior is defined in terms of value dependence:

• Values other than phi nodes and selectinstructions depend on their operands.
• Phi nodes depend on the operand corresponding totheir dynamic predecessor basic block.
• Select instructions depend on their condition operand and theirselected operand.
• Function arguments depend on the corresponding actual argument valuesin the dynamic callers of their functions.
• Call instructions depend on the retinstructions that dynamically transfer control back to them.
• Invoke instructions depend on theret, resume, or exception-throwingcall instructions that dynamically transfer control back to them.
• Non-volatile loads and stores depend on the most recent stores to allof the referenced memory addresses, following the order in the IR(including loads and stores implied by intrinsics such as@llvm.memcpy.)
• An instruction with externally visible side effects depends on themost recent preceding instruction with externally visible sideeffects, following the order in the IR. (This includes volatileoperations.)
• An instruction control-depends on a terminatorinstruction if the terminator instruction hasmultiple successors and the instruction is always executed whencontrol transfers to one of the successors, and may not be executedwhen control is transferred to another.
• Additionally, an instruction also control-depends on a terminatorinstruction if the set of instructions it otherwise depends on wouldbe different if the terminator had transferred control to a differentsuccessor.
• Dependence is transitive.
• Vector elements may be independently poisoned. Therefore, transformson instructions such as shufflevector must be careful to propagatepoison across values or elements only as allowed by the original code.

An instruction that depends on a poison value, produces a poison valueitself. A poison value may be relaxed into anundef value, which takes an arbitrary bit-pattern.Propagation of poison can be stopped with thefreeze instruction.

This means that immediate undefined behavior occurs if a poison value isused as an instruction operand that has any values that trigger undefinedbehavior. Notably this includes (but is not limited to):

• The pointer operand of a load, store orany other pointer dereferencing instruction (independent of addressspace).
• The divisor operand of a udiv, sdiv, urem or sreminstruction.
• The condition operand of a br instruction.
• The callee operand of a call or invokeinstruction.

Here are some examples:

entry:
  %poison = sub nuw i32 0, 1           ; Results in a poison value.
  %still_poison = and i32 %poison, 0   ; 0, but also poison.
  %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison
  store i32 0, i32* %poison_yet_again  ; Undefined behavior due to
                                       ; store to poison.

  store i32 %poison, i32* @g           ; Poison value stored to memory.
  %poison2 = load i32, i32* @g         ; Poison value loaded back from memory.

  %narrowaddr = bitcast i32* @g to i16*
  %wideaddr = bitcast i32* @g to i64*
  %poison3 = load i16, i16* %narrowaddr ; Returns a poison value.
  %poison4 = load i64, i64* %wideaddr   ; Returns a poison value.

  %cmp = icmp slt i32 %poison, 0       ; Returns a poison value.
  br i1 %cmp, label %end, label %end   ; undefined behavior

end:

Addresses of Basic Blocks

blockaddress(@function, %block)

The ‘blockaddress’ constant computes the address of the specifiedbasic block in the specified function, and always has an i8* type.Taking the address of the entry block is illegal.

This value only has defined behavior when used as an operand to the‘indirectbr’ or ‘callbr’instruction, orfor comparisons against null. Pointer equality tests between labels addressesresults in undefined behavior — though, again, comparison against null is ok,and no label is equal to the null pointer. This may be passed around as anopaque pointer sized value as long as the bits are not inspected. Thisallows ptrtoint and arithmetic to be performed on these values solong as the original value is reconstituted before the indirectbr orcallbr instruction.

Finally, some targets may provide defined semantics when using the valueas the operand to an inline assembly, but that is target specific.

Constant Expressions

Constant expressions are used to allow expressions involving otherconstants to be used as constants. Constant expressions may be of anyfirst class type and may involve any LLVM operationthat does not have side effects (e.g. load and call are not supported).The following is the syntax for constant expressions:

• trunc (CST to TYPE)
• Perform the trunc operation on constants.
• zext (CST to TYPE)
• Perform the zext operation on constants.
• sext (CST to TYPE)
• Perform the sext operation on constants.
• fptrunc (CST to TYPE)
• Truncate a floating-point constant to another floating-point type.The size of CST must be larger than the size of TYPE. Both typesmust be floating-point.
• fpext (CST to TYPE)
• Floating-point extend a constant to another type. The size of CSTmust be smaller or equal to the size of TYPE. Both types must befloating-point.
• fptoui (CST to TYPE)
• Convert a floating-point constant to the corresponding unsignedinteger constant. TYPE must be a scalar or vector integer type. CSTmust be of scalar or vector floating-point type. Both CST and TYPEmust be scalars, or vectors of the same number of elements. If thevalue won’t fit in the integer type, the result is apoison value.
• fptosi (CST to TYPE)
• Convert a floating-point constant to the corresponding signedinteger constant. TYPE must be a scalar or vector integer type. CSTmust be of scalar or vector floating-point type. Both CST and TYPEmust be scalars, or vectors of the same number of elements. If thevalue won’t fit in the integer type, the result is apoison value.
• uitofp (CST to TYPE)
• Convert an unsigned integer constant to the correspondingfloating-point constant. TYPE must be a scalar or vector floating-pointtype. CST must be of scalar or vector integer type. Both CST and TYPE mustbe scalars, or vectors of the same number of elements.
• sitofp (CST to TYPE)
• Convert a signed integer constant to the corresponding floating-pointconstant. TYPE must be a scalar or vector floating-point type.CST must be of scalar or vector integer type. Both CST and TYPE mustbe scalars, or vectors of the same number of elements.
• ptrtoint (CST to TYPE)
• Perform the ptrtoint operation on constants.
• inttoptr (CST to TYPE)
• Perform the inttoptr operation on constants.This one is really dangerous!
• bitcast (CST to TYPE)
• Convert a constant, CST, to another TYPE.The constraints of the operands are the same as those for thebitcast instruction.
• addrspacecast (CST to TYPE)
• Convert a constant pointer or constant vector of pointer, CST, to anotherTYPE in a different address space. The constraints of the operands are thesame as those for the addrspacecast instruction.
• getelementptr (TY, CSTPTR, IDX0, IDX1, …), getelementptr inbounds (TY, CSTPTR, IDX0, IDX1, …)
• Perform the getelementptr operation onconstants. As with the getelementptrinstruction, the index list may have one or more indexes, which arerequired to make sense for the type of “pointer to TY”.
• select (COND, VAL1, VAL2)
• Perform the select operation on constants.
• icmp COND (VAL1, VAL2)
• Perform the icmp operation on constants.
• fcmp COND (VAL1, VAL2)
• Perform the fcmp operation on constants.
• extractelement (VAL, IDX)
• Perform the extractelement operation onconstants.
• insertelement (VAL, ELT, IDX)
• Perform the insertelement operation onconstants.
• shufflevector (VEC1, VEC2, IDXMASK)
• Perform the shufflevector operation onconstants.
• extractvalue (VAL, IDX0, IDX1, …)
• Perform the extractvalue operation onconstants. The index list is interpreted in a similar manner asindices in a ‘getelementptr’ operation. Atleast one index value must be specified.
• insertvalue (VAL, ELT, IDX0, IDX1, …)
• Perform the insertvalue operation on constants.The index list is interpreted in a similar manner as indices in a‘getelementptr’ operation. At least one indexvalue must be specified.
• OPCODE (LHS, RHS)
• Perform the specified operation of the LHS and RHS constants. OPCODEmay be any of the binary or bitwisebinary operations. The constraints on operands arethe same as those for the corresponding instruction (e.g. no bitwiseoperations on floating-point values are allowed).

Other Values

Inline Assembler Expressions

LLVM supports inline assembler expressions (as opposed to Module-LevelInline Assembly) through the use of a special value. This valuerepresents the inline assembler as a template string (containing theinstructions to emit), a list of operand constraints (stored as a string), aflag that indicates whether or not the inline asm expression has side effects,and a flag indicating whether the function containing the asm needs to align itsstack conservatively.

The template string supports argument substitution of the operands using “$”followed by a number, to indicate substitution of the given register/memorylocation, as specified by the constraint string. “${NUM:MODIFIER}” may alsobe used, where MODIFIER is a target-specific annotation for how to print theoperand (See Asm template argument modifiers).

A literal “$” may be included by using “$$” in the template. To includeother special characters into the output, the usual “\XX” escapes may beused, just as in other strings. Note that after template substitution, theresulting assembly string is parsed by LLVM’s integrated assembler unless it isdisabled – even when emitting a .s file – and thus must contain assemblysyntax known to LLVM.

LLVM also supports a few more substitutions useful for writing inline assembly:

• ${:uid}: Expands to a decimal integer unique to this inline assembly blob.This substitution is useful when declaring a local label. Many standardcompiler optimizations, such as inlining, may duplicate an inline asm blob.Adding a blob-unique identifier ensures that the two labels will not conflictduring assembly. This is used to implement GCC’s %= special formatstring.
• ${:comment}: Expands to the comment character of the current target’sassembly dialect. This is usually #, but many targets use other strings,such as ;, //, or !.
• ${:private}: Expands to the assembler private label prefix. Labels withthis prefix will not appear in the symbol table of the assembled object.Typically the prefix is L, but targets may use other strings. .L isrelatively popular.

LLVM’s support for inline asm is modeled closely on the requirements of Clang’sGCC-compatible inline-asm support. Thus, the feature-set and the constraint andmodifier codes listed here are similar or identical to those in GCC’s inline asmsupport. However, to be clear, the syntax of the template and constraint stringsdescribed here is not the same as the syntax accepted by GCC and Clang, and,while most constraint letters are passed through as-is by Clang, some gettranslated to other codes when converting from the C source to the LLVMassembly.

An example inline assembler expression is:

i32 (i32) asm "bswap $0", "=r,r"

Inline assembler expressions may only be used as the callee operandof a call or an invoke instruction.Thus, typically we have:

%X = call i32 asm "bswap $0", "=r,r"(i32 %Y)

Inline asms with side effects not visible in the constraint list must bemarked as having side effects. This is done through the use of the‘sideeffect’ keyword, like so:

call void asm sideeffect "eieio", ""()

In some cases inline asms will contain code that will not work unlessthe stack is aligned in some way, such as calls or SSE instructions onx86, yet will not contain code that does that alignment within the asm.The compiler should make conservative assumptions about what the asmmight contain and should generate its usual stack alignment code in theprologue if the ‘alignstack’ keyword is present:

call void asm alignstack "eieio", ""()

Inline asms also support using non-standard assembly dialects. Theassumed dialect is ATT. When the ‘inteldialect’ keyword is present,the inline asm is using the Intel dialect. Currently, ATT and Intel arethe only supported dialects. An example is:

call void asm inteldialect "eieio", ""()

If multiple keywords appear the ‘sideeffect’ keyword must comefirst, the ‘alignstack’ keyword second and the ‘inteldialect’keyword last.

Inline Asm Constraint String

The constraint list is a comma-separated string, each element containing one ormore constraint codes.

For each element in the constraint list an appropriate register or memoryoperand will be chosen, and it will be made available to assembly templatestring expansion as $0 for the first constraint in the list, $1 for thesecond, etc.

There are three different types of constraints, which are distinguished by aprefix symbol in front of the constraint code: Output, Input, and Clobber. Theconstraints must always be given in that order: outputs first, then inputs, thenclobbers. They cannot be intermingled.

There are also three different categories of constraint codes:

• Register constraint. This is either a register class, or a fixed physicalregister. This kind of constraint will allocate a register, and if necessary,bitcast the argument or result to the appropriate type.
• Memory constraint. This kind of constraint is for use with an instructiontaking a memory operand. Different constraints allow for different addressingmodes used by the target.
• Immediate value constraint. This kind of constraint is for an integer or otherimmediate value which can be rendered directly into an instruction. Thevarious target-specific constraints allow the selection of a value in theproper range for the instruction you wish to use it with.

Output constraints

Output constraints are specified by an “=” prefix (e.g. “=r”). Thisindicates that the assembly will write to this operand, and the operand willthen be made available as a return value of the asm expression. Outputconstraints do not consume an argument from the call instruction. (Except, seebelow about indirect outputs).

Normally, it is expected that no output locations are written to by the assemblyexpression until all of the inputs have been read. As such, LLVM may assignthe same register to an output and an input. If this is not safe (e.g. if theassembly contains two instructions, where the first writes to one output, andthe second reads an input and writes to a second output), then the “&”modifier must be used (e.g. “=&r”) to specify that the output is an“early-clobber” output. Marking an output as “early-clobber” ensures that LLVMwill not use the same register for any inputs (other than an input tied to thisoutput).

Input constraints

Input constraints do not have a prefix – just the constraint codes. Each inputconstraint will consume one argument from the call instruction. It is notpermitted for the asm to write to any input register or memory location (unlessthat input is tied to an output). Note also that multiple inputs may all beassigned to the same register, if LLVM can determine that they necessarily allcontain the same value.

Instead of providing a Constraint Code, input constraints may also “tie”themselves to an output constraint, by providing an integer as the constraintstring. Tied inputs still consume an argument from the call instruction, andtake up a position in the asm template numbering as is usual – they will simplybe constrained to always use the same register as the output they’ve been tiedto. For example, a constraint string of “=r,0” says to assign a register foroutput, and use that register as an input as well (it being the 0’thconstraint).

It is permitted to tie an input to an “early-clobber” output. In that case, noother input may share the same register as the input tied to the early-clobber(even when the other input has the same value).

You may only tie an input to an output which has a register constraint, not amemory constraint. Only a single input may be tied to an output.

There is also an “interesting” feature which deserves a bit of explanation: if aregister class constraint allocates a register which is too small for the valuetype operand provided as input, the input value will be split into multipleregisters, and all of them passed to the inline asm.

However, this feature is often not as useful as you might think.

Firstly, the registers are not guaranteed to be consecutive. So, on thosearchitectures that have instructions which operate on multiple consecutiveinstructions, this is not an appropriate way to support them. (e.g. the 32-bitSparcV8 has a 64-bit load, which instruction takes a single 32-bit register. Thehardware then loads into both the named register, and the next register. Thisfeature of inline asm would not be useful to support that.)

A few of the targets provide a template string modifier allowing explicit accessto the second register of a two-register operand (e.g. MIPS L, M, andD). On such an architecture, you can actually access the second allocatedregister (yet, still, not any subsequent ones). But, in that case, you’re stillprobably better off simply splitting the value into two separate operands, forclarity. (e.g. see the description of the A constraint on X86, which,despite existing only for use with this feature, is not really a good idea touse)

Indirect inputs and outputs

Indirect output or input constraints can be specified by the “*” modifier(which goes after the “=” in case of an output). This indicates that the asmwill write to or read from the contents of an address provided as an inputargument. (Note that in this way, indirect outputs act more like an input thanan output: just like an input, they consume an argument of the call expression,rather than producing a return value. An indirect output constraint is an“output” only in that the asm is expected to write to the contents of the inputmemory location, instead of just read from it).

This is most typically used for memory constraint, e.g. “=*m”, to pass theaddress of a variable as a value.

It is also possible to use an indirect register constraint, but only on output(e.g. “=*r”). This will cause LLVM to allocate a register for an outputvalue normally, and then, separately emit a store to the address provided asinput, after the provided inline asm. (It’s not clear what value thisfunctionality provides, compared to writing the store explicitly after the asmstatement, and it can only produce worse code, since it bypasses manyoptimization passes. I would recommend not using it.)

Clobber constraints

A clobber constraint is indicated by a “~” prefix. A clobber does notconsume an input operand, nor generate an output. Clobbers cannot use any of thegeneral constraint code letters – they may use only explicit registerconstraints, e.g. “~{eax}”. The one exception is that a clobber string of“~{memory}” indicates that the assembly writes to arbitrary undeclaredmemory locations – not only the memory pointed to by a declared indirectoutput.

Note that clobbering named registers that are also present in outputconstraints is not legal.

Constraint Codes

After a potential prefix comes constraint code, or codes.

A Constraint Code is either a single letter (e.g. “r”), a “^” characterfollowed by two letters (e.g. “^wc”), or “{” register-name “}”(e.g. “{eax}”).

The one and two letter constraint codes are typically chosen to be the same asGCC’s constraint codes.

A single constraint may include one or more than constraint code in it, leavingit up to LLVM to choose which one to use. This is included mainly forcompatibility with the translation of GCC inline asm coming from clang.

There are two ways to specify alternatives, and either or both may be used in aninline asm constraint list:

• Append the codes to each other, making a constraint code set. E.g. “im”or “{eax}m”. This means “choose any of the options in the set”. Thechoice of constraint is made independently for each constraint in theconstraint list.
• Use “|” between constraint code sets, creating alternatives. Everyconstraint in the constraint list must have the same number of alternativesets. With this syntax, the same alternative in all of the items in theconstraint list will be chosen together.Putting those together, you might have a two operand constraint string like"rm|r,ri|rm". This indicates that if operand 0 is r or m, thenoperand 1 may be one of r or i. If operand 0 is r, then operand 1may be one of r or m. But, operand 0 and 1 cannot both be of type m.

However, the use of either of the alternatives features is NOT recommended, asLLVM is not able to make an intelligent choice about which one to use. (At thepoint it currently needs to choose, not enough information is available to do soin a smart way.) Thus, it simply tries to make a choice that’s most likely tocompile, not one that will be optimal performance. (e.g., given “rm”, it’llalways choose to use memory, not registers). And, if given multiple registers,or multiple register classes, it will simply choose the first one. (In fact, itdoesn’t currently even ensure explicitly specified physical registers areunique, so specifying multiple physical registers as alternatives, like{r11}{r12},{r11}{r12}, will assign r11 to both operands, not at all what wasintended.)

Supported Constraint Code List

The constraint codes are, in general, expected to behave the same way they do inGCC. LLVM’s support is often implemented on an ‘as-needed’ basis, to support Cinline asm code which was supported by GCC. A mismatch in behavior between LLVMand GCC likely indicates a bug in LLVM.

Some constraint codes are typically supported by all targets:

• r: A register in the target’s general purpose register class.
• m: A memory address operand. It is target-specific what addressing modesare supported, typical examples are register, or register + register offset,or register + immediate offset (of some target-specific size).
• i: An integer constant (of target-specific width). Allows either a simpleimmediate, or a relocatable value.
• n: An integer constant – not including relocatable values.
• s: An integer constant, but allowing only relocatable values.
• X: Allows an operand of any kind, no constraint whatsoever. Typicallyuseful to pass a label for an asm branch or call.
• {register-name}: Requires exactly the named physical register.

Other constraints are target-specific:

AArch64:

• z: An immediate integer 0. Outputs WZR or XZR, as appropriate.
• I: An immediate integer valid for an ADD or SUB instruction,i.e. 0 to 4095 with optional shift by 12.
• J: An immediate integer that, when negated, is valid for an ADD orSUB instruction, i.e. -1 to -4095 with optional left shift by 12.
• K: An immediate integer that is valid for the ‘bitmask immediate 32’ of alogical instruction like AND, EOR, or ORR with a 32-bit register.
• L: An immediate integer that is valid for the ‘bitmask immediate 64’ of alogical instruction like AND, EOR, or ORR with a 64-bit register.
• M: An immediate integer for use with the MOV assembly alias on a32-bit register. This is a superset of K: in addition to the bitmaskimmediate, also allows immediate integers which can be loaded with a singleMOVZ or MOVL instruction.
• N: An immediate integer for use with the MOV assembly alias on a64-bit register. This is a superset of L.
• Q: Memory address operand must be in a single register (nooffsets). (However, LLVM currently does this for the m constraint aswell.)
• r: A 32 or 64-bit integer register (W or X).
• w: A 32, 64, or 128-bit floating-point, SIMD or SVE vector register.
• x: Like w, but restricted to registers 0 to 15 inclusive.
• y: Like w, but restricted to SVE vector registers Z0 to Z7 inclusive.
• Upl: One of the low eight SVE predicate registers (P0 to P7)
• Upa: Any of the SVE predicate registers (P0 to P15)

AMDGPU:

• r: A 32 or 64-bit integer register.
• [0-9]v: The 32-bit VGPR register, number 0-9.
• [0-9]s: The 32-bit SGPR register, number 0-9.

All ARM modes:

• Q, Um, Un, Uq, Us, Ut, Uv, Uy: Memory addressoperand. Treated the same as operand m, at the moment.
• Te: An even general-purpose 32-bit integer register: r0,r2,…,r12,r14
• To: An odd general-purpose 32-bit integer register: r1,r3,…,r11

ARM and ARM’s Thumb2 mode: