1 ==============================
2 LLVM Language Reference Manual
3 ==============================
12 This document is a reference manual for the LLVM assembly language. LLVM
13 is a Static Single Assignment (SSA) based representation that provides
14 type safety, low-level operations, flexibility, and the capability of
15 representing 'all' high-level languages cleanly. It is the common code
16 representation used throughout all phases of the LLVM compilation
22 The LLVM code representation is designed to be used in three different
23 forms: as an in-memory compiler IR, as an on-disk bitcode representation
24 (suitable for fast loading by a Just-In-Time compiler), and as a human
25 readable assembly language representation. This allows LLVM to provide a
26 powerful intermediate representation for efficient compiler
27 transformations and analysis, while providing a natural means to debug
28 and visualize the transformations. The three different forms of LLVM are
29 all equivalent. This document describes the human readable
30 representation and notation.
32 The LLVM representation aims to be light-weight and low-level while
33 being expressive, typed, and extensible at the same time. It aims to be
34 a "universal IR" of sorts, by being at a low enough level that
35 high-level ideas may be cleanly mapped to it (similar to how
36 microprocessors are "universal IR's", allowing many source languages to
37 be mapped to them). By providing type information, LLVM can be used as
38 the target of optimizations: for example, through pointer analysis, it
39 can be proven that a C automatic variable is never accessed outside of
40 the current function, allowing it to be promoted to a simple SSA value
41 instead of a memory location.
48 It is important to note that this document describes 'well formed' LLVM
49 assembly language. There is a difference between what the parser accepts
50 and what is considered 'well formed'. For example, the following
51 instruction is syntactically okay, but not well formed:
57 because the definition of ``%x`` does not dominate all of its uses. The
58 LLVM infrastructure provides a verification pass that may be used to
59 verify that an LLVM module is well formed. This pass is automatically
60 run by the parser after parsing input assembly and by the optimizer
61 before it outputs bitcode. The violations pointed out by the verifier
62 pass indicate bugs in transformation passes or input to the parser.
69 LLVM identifiers come in two basic types: global and local. Global
70 identifiers (functions, global variables) begin with the ``'@'``
71 character. Local identifiers (register names, types) begin with the
72 ``'%'`` character. Additionally, there are three different formats for
73 identifiers, for different purposes:
75 #. Named values are represented as a string of characters with their
76 prefix. For example, ``%foo``, ``@DivisionByZero``,
77 ``%a.really.long.identifier``. The actual regular expression used is
78 '``[%@][-a-zA-Z$._][-a-zA-Z$._0-9]*``'. Identifiers that require other
79 characters in their names can be surrounded with quotes. Special
80 characters may be escaped using ``"\xx"`` where ``xx`` is the ASCII
81 code for the character in hexadecimal. In this way, any character can
82 be used in a name value, even quotes themselves. The ``"\01"`` prefix
83 can be used on global values to suppress mangling.
84 #. Unnamed values are represented as an unsigned numeric value with
85 their prefix. For example, ``%12``, ``@2``, ``%44``.
86 #. Constants, which are described in the section Constants_ below.
88 LLVM requires that values start with a prefix for two reasons: Compilers
89 don't need to worry about name clashes with reserved words, and the set
90 of reserved words may be expanded in the future without penalty.
91 Additionally, unnamed identifiers allow a compiler to quickly come up
92 with a temporary variable without having to avoid symbol table
95 Reserved words in LLVM are very similar to reserved words in other
96 languages. There are keywords for different opcodes ('``add``',
97 '``bitcast``', '``ret``', etc...), for primitive type names ('``void``',
98 '``i32``', etc...), and others. These reserved words cannot conflict
99 with variable names, because none of them start with a prefix character
100 (``'%'`` or ``'@'``).
102 Here is an example of LLVM code to multiply the integer variable
109 %result = mul i32 %X, 8
111 After strength reduction:
115 %result = shl i32 %X, 3
121 %0 = add i32 %X, %X ; yields i32:%0
122 %1 = add i32 %0, %0 ; yields i32:%1
123 %result = add i32 %1, %1
125 This last way of multiplying ``%X`` by 8 illustrates several important
126 lexical features of LLVM:
128 #. Comments are delimited with a '``;``' and go until the end of line.
129 #. Unnamed temporaries are created when the result of a computation is
130 not assigned to a named value.
131 #. Unnamed temporaries are numbered sequentially (using a per-function
132 incrementing counter, starting with 0). Note that basic blocks and unnamed
133 function parameters are included in this numbering. For example, if the
134 entry basic block is not given a label name and all function parameters are
135 named, then it will get number 0.
137 It also shows a convention that we follow in this document. When
138 demonstrating instructions, we will follow an instruction with a comment
139 that defines the type and name of value produced.
147 LLVM programs are composed of ``Module``'s, each of which is a
148 translation unit of the input programs. Each module consists of
149 functions, global variables, and symbol table entries. Modules may be
150 combined together with the LLVM linker, which merges function (and
151 global variable) definitions, resolves forward declarations, and merges
152 symbol table entries. Here is an example of the "hello world" module:
156 ; Declare the string constant as a global constant.
157 @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
159 ; External declaration of the puts function
160 declare i32 @puts(i8* nocapture) nounwind
162 ; Definition of main function
163 define i32 @main() { ; i32()*
164 ; Convert [13 x i8]* to i8*...
165 %cast210 = getelementptr [13 x i8], [13 x i8]* @.str, i64 0, i64 0
167 ; Call puts function to write out the string to stdout.
168 call i32 @puts(i8* %cast210)
173 !0 = !{i32 42, null, !"string"}
176 This example is made up of a :ref:`global variable <globalvars>` named
177 "``.str``", an external declaration of the "``puts``" function, a
178 :ref:`function definition <functionstructure>` for "``main``" and
179 :ref:`named metadata <namedmetadatastructure>` "``foo``".
181 In general, a module is made up of a list of global values (where both
182 functions and global variables are global values). Global values are
183 represented by a pointer to a memory location (in this case, a pointer
184 to an array of char, and a pointer to a function), and have one of the
185 following :ref:`linkage types <linkage>`.
192 All Global Variables and Functions have one of the following types of
196 Global values with "``private``" linkage are only directly
197 accessible by objects in the current module. In particular, linking
198 code into a module with a private global value may cause the
199 private to be renamed as necessary to avoid collisions. Because the
200 symbol is private to the module, all references can be updated. This
201 doesn't show up in any symbol table in the object file.
203 Similar to private, but the value shows as a local symbol
204 (``STB_LOCAL`` in the case of ELF) in the object file. This
205 corresponds to the notion of the '``static``' keyword in C.
206 ``available_externally``
207 Globals with "``available_externally``" linkage are never emitted into
208 the object file corresponding to the LLVM module. From the linker's
209 perspective, an ``available_externally`` global is equivalent to
210 an external declaration. They exist to allow inlining and other
211 optimizations to take place given knowledge of the definition of the
212 global, which is known to be somewhere outside the module. Globals
213 with ``available_externally`` linkage are allowed to be discarded at
214 will, and allow inlining and other optimizations. This linkage type is
215 only allowed on definitions, not declarations.
217 Globals with "``linkonce``" linkage are merged with other globals of
218 the same name when linkage occurs. This can be used to implement
219 some forms of inline functions, templates, or other code which must
220 be generated in each translation unit that uses it, but where the
221 body may be overridden with a more definitive definition later.
222 Unreferenced ``linkonce`` globals are allowed to be discarded. Note
223 that ``linkonce`` linkage does not actually allow the optimizer to
224 inline the body of this function into callers because it doesn't
225 know if this definition of the function is the definitive definition
226 within the program or whether it will be overridden by a stronger
227 definition. To enable inlining and other optimizations, use
228 "``linkonce_odr``" linkage.
230 "``weak``" linkage has the same merging semantics as ``linkonce``
231 linkage, except that unreferenced globals with ``weak`` linkage may
232 not be discarded. This is used for globals that are declared "weak"
235 "``common``" linkage is most similar to "``weak``" linkage, but they
236 are used for tentative definitions in C, such as "``int X;``" at
237 global scope. Symbols with "``common``" linkage are merged in the
238 same way as ``weak symbols``, and they may not be deleted if
239 unreferenced. ``common`` symbols may not have an explicit section,
240 must have a zero initializer, and may not be marked
241 ':ref:`constant <globalvars>`'. Functions and aliases may not have
244 .. _linkage_appending:
247 "``appending``" linkage may only be applied to global variables of
248 pointer to array type. When two global variables with appending
249 linkage are linked together, the two global arrays are appended
250 together. This is the LLVM, typesafe, equivalent of having the
251 system linker append together "sections" with identical names when
254 Unfortunately this doesn't correspond to any feature in .o files, so it
255 can only be used for variables like ``llvm.global_ctors`` which llvm
256 interprets specially.
259 The semantics of this linkage follow the ELF object file model: the
260 symbol is weak until linked, if not linked, the symbol becomes null
261 instead of being an undefined reference.
262 ``linkonce_odr``, ``weak_odr``
263 Some languages allow differing globals to be merged, such as two
264 functions with different semantics. Other languages, such as
265 ``C++``, ensure that only equivalent globals are ever merged (the
266 "one definition rule" --- "ODR"). Such languages can use the
267 ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
268 global will only be merged with equivalent globals. These linkage
269 types are otherwise the same as their non-``odr`` versions.
271 If none of the above identifiers are used, the global is externally
272 visible, meaning that it participates in linkage and can be used to
273 resolve external symbol references.
275 It is illegal for a function *declaration* to have any linkage type
276 other than ``external`` or ``extern_weak``.
283 LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and
284 :ref:`invokes <i_invoke>` can all have an optional calling convention
285 specified for the call. The calling convention of any pair of dynamic
286 caller/callee must match, or the behavior of the program is undefined.
287 The following calling conventions are supported by LLVM, and more may be
290 "``ccc``" - The C calling convention
291 This calling convention (the default if no other calling convention
292 is specified) matches the target C calling conventions. This calling
293 convention supports varargs function calls and tolerates some
294 mismatch in the declared prototype and implemented declaration of
295 the function (as does normal C).
296 "``fastcc``" - The fast calling convention
297 This calling convention attempts to make calls as fast as possible
298 (e.g. by passing things in registers). This calling convention
299 allows the target to use whatever tricks it wants to produce fast
300 code for the target, without having to conform to an externally
301 specified ABI (Application Binary Interface). `Tail calls can only
302 be optimized when this, the GHC or the HiPE convention is
303 used. <CodeGenerator.html#id80>`_ This calling convention does not
304 support varargs and requires the prototype of all callees to exactly
305 match the prototype of the function definition.
306 "``coldcc``" - The cold calling convention
307 This calling convention attempts to make code in the caller as
308 efficient as possible under the assumption that the call is not
309 commonly executed. As such, these calls often preserve all registers
310 so that the call does not break any live ranges in the caller side.
311 This calling convention does not support varargs and requires the
312 prototype of all callees to exactly match the prototype of the
313 function definition. Furthermore the inliner doesn't consider such function
315 "``cc 10``" - GHC convention
316 This calling convention has been implemented specifically for use by
317 the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_.
318 It passes everything in registers, going to extremes to achieve this
319 by disabling callee save registers. This calling convention should
320 not be used lightly but only for specific situations such as an
321 alternative to the *register pinning* performance technique often
322 used when implementing functional programming languages. At the
323 moment only X86 supports this convention and it has the following
326 - On *X86-32* only supports up to 4 bit type parameters. No
327 floating-point types are supported.
328 - On *X86-64* only supports up to 10 bit type parameters and 6
329 floating-point parameters.
331 This calling convention supports `tail call
332 optimization <CodeGenerator.html#id80>`_ but requires both the
333 caller and callee are using it.
334 "``cc 11``" - The HiPE calling convention
335 This calling convention has been implemented specifically for use by
336 the `High-Performance Erlang
337 (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the*
338 native code compiler of the `Ericsson's Open Source Erlang/OTP
339 system <http://www.erlang.org/download.shtml>`_. It uses more
340 registers for argument passing than the ordinary C calling
341 convention and defines no callee-saved registers. The calling
342 convention properly supports `tail call
343 optimization <CodeGenerator.html#id80>`_ but requires that both the
344 caller and the callee use it. It uses a *register pinning*
345 mechanism, similar to GHC's convention, for keeping frequently
346 accessed runtime components pinned to specific hardware registers.
347 At the moment only X86 supports this convention (both 32 and 64
349 "``webkit_jscc``" - WebKit's JavaScript calling convention
350 This calling convention has been implemented for `WebKit FTL JIT
351 <https://trac.webkit.org/wiki/FTLJIT>`_. It passes arguments on the
352 stack right to left (as cdecl does), and returns a value in the
353 platform's customary return register.
354 "``anyregcc``" - Dynamic calling convention for code patching
355 This is a special convention that supports patching an arbitrary code
356 sequence in place of a call site. This convention forces the call
357 arguments into registers but allows them to be dynamically
358 allocated. This can currently only be used with calls to
359 llvm.experimental.patchpoint because only this intrinsic records
360 the location of its arguments in a side table. See :doc:`StackMaps`.
361 "``preserve_mostcc``" - The `PreserveMost` calling convention
362 This calling convention attempts to make the code in the caller as
363 unintrusive as possible. This convention behaves identically to the `C`
364 calling convention on how arguments and return values are passed, but it
365 uses a different set of caller/callee-saved registers. This alleviates the
366 burden of saving and recovering a large register set before and after the
367 call in the caller. If the arguments are passed in callee-saved registers,
368 then they will be preserved by the callee across the call. This doesn't
369 apply for values returned in callee-saved registers.
371 - On X86-64 the callee preserves all general purpose registers, except for
372 R11. R11 can be used as a scratch register. Floating-point registers
373 (XMMs/YMMs) are not preserved and need to be saved by the caller.
375 The idea behind this convention is to support calls to runtime functions
376 that have a hot path and a cold path. The hot path is usually a small piece
377 of code that doesn't use many registers. The cold path might need to call out to
378 another function and therefore only needs to preserve the caller-saved
379 registers, which haven't already been saved by the caller. The
380 `PreserveMost` calling convention is very similar to the `cold` calling
381 convention in terms of caller/callee-saved registers, but they are used for
382 different types of function calls. `coldcc` is for function calls that are
383 rarely executed, whereas `preserve_mostcc` function calls are intended to be
384 on the hot path and definitely executed a lot. Furthermore `preserve_mostcc`
385 doesn't prevent the inliner from inlining the function call.
387 This calling convention will be used by a future version of the ObjectiveC
388 runtime and should therefore still be considered experimental at this time.
389 Although this convention was created to optimize certain runtime calls to
390 the ObjectiveC runtime, it is not limited to this runtime and might be used
391 by other runtimes in the future too. The current implementation only
392 supports X86-64, but the intention is to support more architectures in the
394 "``preserve_allcc``" - The `PreserveAll` calling convention
395 This calling convention attempts to make the code in the caller even less
396 intrusive than the `PreserveMost` calling convention. This calling
397 convention also behaves identical to the `C` calling convention on how
398 arguments and return values are passed, but it uses a different set of
399 caller/callee-saved registers. This removes the burden of saving and
400 recovering a large register set before and after the call in the caller. If
401 the arguments are passed in callee-saved registers, then they will be
402 preserved by the callee across the call. This doesn't apply for values
403 returned in callee-saved registers.
405 - On X86-64 the callee preserves all general purpose registers, except for
406 R11. R11 can be used as a scratch register. Furthermore it also preserves
407 all floating-point registers (XMMs/YMMs).
409 The idea behind this convention is to support calls to runtime functions
410 that don't need to call out to any other functions.
412 This calling convention, like the `PreserveMost` calling convention, will be
413 used by a future version of the ObjectiveC runtime and should be considered
414 experimental at this time.
415 "``cxx_fast_tlscc``" - The `CXX_FAST_TLS` calling convention for access functions
416 Clang generates an access function to access C++-style TLS. The access
417 function generally has an entry block, an exit block and an initialization
418 block that is run at the first time. The entry and exit blocks can access
419 a few TLS IR variables, each access will be lowered to a platform-specific
422 This calling convention aims to minimize overhead in the caller by
423 preserving as many registers as possible (all the registers that are
424 preserved on the fast path, composed of the entry and exit blocks).
426 This calling convention behaves identical to the `C` calling convention on
427 how arguments and return values are passed, but it uses a different set of
428 caller/callee-saved registers.
430 Given that each platform has its own lowering sequence, hence its own set
431 of preserved registers, we can't use the existing `PreserveMost`.
433 - On X86-64 the callee preserves all general purpose registers, except for
435 "``swiftcc``" - This calling convention is used for Swift language.
436 - On X86-64 RCX and R8 are available for additional integer returns, and
437 XMM2 and XMM3 are available for additional FP/vector returns.
438 - On iOS platforms, we use AAPCS-VFP calling convention.
439 "``cc <n>``" - Numbered convention
440 Any calling convention may be specified by number, allowing
441 target-specific calling conventions to be used. Target specific
442 calling conventions start at 64.
444 More calling conventions can be added/defined on an as-needed basis, to
445 support Pascal conventions or any other well-known target-independent
448 .. _visibilitystyles:
453 All Global Variables and Functions have one of the following visibility
456 "``default``" - Default style
457 On targets that use the ELF object file format, default visibility
458 means that the declaration is visible to other modules and, in
459 shared libraries, means that the declared entity may be overridden.
460 On Darwin, default visibility means that the declaration is visible
461 to other modules. Default visibility corresponds to "external
462 linkage" in the language.
463 "``hidden``" - Hidden style
464 Two declarations of an object with hidden visibility refer to the
465 same object if they are in the same shared object. Usually, hidden
466 visibility indicates that the symbol will not be placed into the
467 dynamic symbol table, so no other module (executable or shared
468 library) can reference it directly.
469 "``protected``" - Protected style
470 On ELF, protected visibility indicates that the symbol will be
471 placed in the dynamic symbol table, but that references within the
472 defining module will bind to the local symbol. That is, the symbol
473 cannot be overridden by another module.
475 A symbol with ``internal`` or ``private`` linkage must have ``default``
483 All Global Variables, Functions and Aliases can have one of the following
487 "``dllimport``" causes the compiler to reference a function or variable via
488 a global pointer to a pointer that is set up by the DLL exporting the
489 symbol. On Microsoft Windows targets, the pointer name is formed by
490 combining ``__imp_`` and the function or variable name.
492 "``dllexport``" causes the compiler to provide a global pointer to a pointer
493 in a DLL, so that it can be referenced with the ``dllimport`` attribute. On
494 Microsoft Windows targets, the pointer name is formed by combining
495 ``__imp_`` and the function or variable name. Since this storage class
496 exists for defining a dll interface, the compiler, assembler and linker know
497 it is externally referenced and must refrain from deleting the symbol.
501 Thread Local Storage Models
502 ---------------------------
504 A variable may be defined as ``thread_local``, which means that it will
505 not be shared by threads (each thread will have a separated copy of the
506 variable). Not all targets support thread-local variables. Optionally, a
507 TLS model may be specified:
510 For variables that are only used within the current shared library.
512 For variables in modules that will not be loaded dynamically.
514 For variables defined in the executable and only used within it.
516 If no explicit model is given, the "general dynamic" model is used.
518 The models correspond to the ELF TLS models; see `ELF Handling For
519 Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for
520 more information on under which circumstances the different models may
521 be used. The target may choose a different TLS model if the specified
522 model is not supported, or if a better choice of model can be made.
524 A model can also be specified in an alias, but then it only governs how
525 the alias is accessed. It will not have any effect in the aliasee.
527 For platforms without linker support of ELF TLS model, the -femulated-tls
528 flag can be used to generate GCC compatible emulated TLS code.
530 .. _runtime_preemption_model:
532 Runtime Preemption Specifiers
533 -----------------------------
535 Global variables, functions and aliases may have an optional runtime preemption
536 specifier. If a preemption specifier isn't given explicitly, then a
537 symbol is assumed to be ``dso_preemptable``.
540 Indicates that the function or variable may be replaced by a symbol from
541 outside the linkage unit at runtime.
544 The compiler may assume that a function or variable marked as ``dso_local``
545 will resolve to a symbol within the same linkage unit. Direct access will
546 be generated even if the definition is not within this compilation unit.
553 LLVM IR allows you to specify both "identified" and "literal" :ref:`structure
554 types <t_struct>`. Literal types are uniqued structurally, but identified types
555 are never uniqued. An :ref:`opaque structural type <t_opaque>` can also be used
556 to forward declare a type that is not yet available.
558 An example of an identified structure specification is:
562 %mytype = type { %mytype*, i32 }
564 Prior to the LLVM 3.0 release, identified types were structurally uniqued. Only
565 literal types are uniqued in recent versions of LLVM.
569 Non-Integral Pointer Type
570 -------------------------
572 Note: non-integral pointer types are a work in progress, and they should be
573 considered experimental at this time.
575 LLVM IR optionally allows the frontend to denote pointers in certain address
576 spaces as "non-integral" via the :ref:`datalayout string<langref_datalayout>`.
577 Non-integral pointer types represent pointers that have an *unspecified* bitwise
578 representation; that is, the integral representation may be target dependent or
579 unstable (not backed by a fixed integer).
581 ``inttoptr`` instructions converting integers to non-integral pointer types are
582 ill-typed, and so are ``ptrtoint`` instructions converting values of
583 non-integral pointer types to integers. Vector versions of said instructions
584 are ill-typed as well.
591 Global variables define regions of memory allocated at compilation time
594 Global variable definitions must be initialized.
596 Global variables in other translation units can also be declared, in which
597 case they don't have an initializer.
599 Either global variable definitions or declarations may have an explicit section
600 to be placed in and may have an optional explicit alignment specified. If there
601 is a mismatch between the explicit or inferred section information for the
602 variable declaration and its definition the resulting behavior is undefined.
604 A variable may be defined as a global ``constant``, which indicates that
605 the contents of the variable will **never** be modified (enabling better
606 optimization, allowing the global data to be placed in the read-only
607 section of an executable, etc). Note that variables that need runtime
608 initialization cannot be marked ``constant`` as there is a store to the
611 LLVM explicitly allows *declarations* of global variables to be marked
612 constant, even if the final definition of the global is not. This
613 capability can be used to enable slightly better optimization of the
614 program, but requires the language definition to guarantee that
615 optimizations based on the 'constantness' are valid for the translation
616 units that do not include the definition.
618 As SSA values, global variables define pointer values that are in scope
619 (i.e. they dominate) all basic blocks in the program. Global variables
620 always define a pointer to their "content" type because they describe a
621 region of memory, and all memory objects in LLVM are accessed through
624 Global variables can be marked with ``unnamed_addr`` which indicates
625 that the address is not significant, only the content. Constants marked
626 like this can be merged with other constants if they have the same
627 initializer. Note that a constant with significant address *can* be
628 merged with a ``unnamed_addr`` constant, the result being a constant
629 whose address is significant.
631 If the ``local_unnamed_addr`` attribute is given, the address is known to
632 not be significant within the module.
634 A global variable may be declared to reside in a target-specific
635 numbered address space. For targets that support them, address spaces
636 may affect how optimizations are performed and/or what target
637 instructions are used to access the variable. The default address space
638 is zero. The address space qualifier must precede any other attributes.
640 LLVM allows an explicit section to be specified for globals. If the
641 target supports it, it will emit globals to the section specified.
642 Additionally, the global can placed in a comdat if the target has the necessary
645 External declarations may have an explicit section specified. Section
646 information is retained in LLVM IR for targets that make use of this
647 information. Attaching section information to an external declaration is an
648 assertion that its definition is located in the specified section. If the
649 definition is located in a different section, the behavior is undefined.
651 By default, global initializers are optimized by assuming that global
652 variables defined within the module are not modified from their
653 initial values before the start of the global initializer. This is
654 true even for variables potentially accessible from outside the
655 module, including those with external linkage or appearing in
656 ``@llvm.used`` or dllexported variables. This assumption may be suppressed
657 by marking the variable with ``externally_initialized``.
659 An explicit alignment may be specified for a global, which must be a
660 power of 2. If not present, or if the alignment is set to zero, the
661 alignment of the global is set by the target to whatever it feels
662 convenient. If an explicit alignment is specified, the global is forced
663 to have exactly that alignment. Targets and optimizers are not allowed
664 to over-align the global if the global has an assigned section. In this
665 case, the extra alignment could be observable: for example, code could
666 assume that the globals are densely packed in their section and try to
667 iterate over them as an array, alignment padding would break this
668 iteration. The maximum alignment is ``1 << 29``.
670 Globals can also have a :ref:`DLL storage class <dllstorageclass>`,
671 an optional :ref:`runtime preemption specifier <runtime_preemption_model>`,
672 an optional :ref:`global attributes <glattrs>` and
673 an optional list of attached :ref:`metadata <metadata>`.
675 Variables and aliases can have a
676 :ref:`Thread Local Storage Model <tls_model>`.
678 :ref:`Scalable vectors <t_vector>` cannot be global variables or members of
679 structs or arrays because their size is unknown at compile time.
683 @<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility]
684 [DLLStorageClass] [ThreadLocal]
685 [(unnamed_addr|local_unnamed_addr)] [AddrSpace]
686 [ExternallyInitialized]
687 <global | constant> <Type> [<InitializerConstant>]
688 [, section "name"] [, comdat [($name)]]
689 [, align <Alignment>] (, !name !N)*
691 For example, the following defines a global in a numbered address space
692 with an initializer, section, and alignment:
696 @G = addrspace(5) constant float 1.0, section "foo", align 4
698 The following example just declares a global variable
702 @G = external global i32
704 The following example defines a thread-local global with the
705 ``initialexec`` TLS model:
709 @G = thread_local(initialexec) global i32 0, align 4
711 .. _functionstructure:
716 LLVM function definitions consist of the "``define``" keyword, an
717 optional :ref:`linkage type <linkage>`, an optional :ref:`runtime preemption
718 specifier <runtime_preemption_model>`, an optional :ref:`visibility
719 style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`,
720 an optional :ref:`calling convention <callingconv>`,
721 an optional ``unnamed_addr`` attribute, a return type, an optional
722 :ref:`parameter attribute <paramattrs>` for the return type, a function
723 name, a (possibly empty) argument list (each with optional :ref:`parameter
724 attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`,
725 an optional address space, an optional section, an optional alignment,
726 an optional :ref:`comdat <langref_comdats>`,
727 an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`,
728 an optional :ref:`prologue <prologuedata>`,
729 an optional :ref:`personality <personalityfn>`,
730 an optional list of attached :ref:`metadata <metadata>`,
731 an opening curly brace, a list of basic blocks, and a closing curly brace.
733 LLVM function declarations consist of the "``declare``" keyword, an
734 optional :ref:`linkage type <linkage>`, an optional :ref:`visibility style
735 <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, an
736 optional :ref:`calling convention <callingconv>`, an optional ``unnamed_addr``
737 or ``local_unnamed_addr`` attribute, an optional address space, a return type,
738 an optional :ref:`parameter attribute <paramattrs>` for the return type, a function name, a possibly
739 empty list of arguments, an optional alignment, an optional :ref:`garbage
740 collector name <gc>`, an optional :ref:`prefix <prefixdata>`, and an optional
741 :ref:`prologue <prologuedata>`.
743 A function definition contains a list of basic blocks, forming the CFG (Control
744 Flow Graph) for the function. Each basic block may optionally start with a label
745 (giving the basic block a symbol table entry), contains a list of instructions,
746 and ends with a :ref:`terminator <terminators>` instruction (such as a branch or
747 function return). If an explicit label name is not provided, a block is assigned
748 an implicit numbered label, using the next value from the same counter as used
749 for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a
750 function entry block does not have an explicit label, it will be assigned label
751 "%0", then the first unnamed temporary in that block will be "%1", etc. If a
752 numeric label is explicitly specified, it must match the numeric label that
753 would be used implicitly.
755 The first basic block in a function is special in two ways: it is
756 immediately executed on entrance to the function, and it is not allowed
757 to have predecessor basic blocks (i.e. there can not be any branches to
758 the entry block of a function). Because the block can have no
759 predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`.
761 LLVM allows an explicit section to be specified for functions. If the
762 target supports it, it will emit functions to the section specified.
763 Additionally, the function can be placed in a COMDAT.
765 An explicit alignment may be specified for a function. If not present,
766 or if the alignment is set to zero, the alignment of the function is set
767 by the target to whatever it feels convenient. If an explicit alignment
768 is specified, the function is forced to have at least that much
769 alignment. All alignments must be a power of 2.
771 If the ``unnamed_addr`` attribute is given, the address is known to not
772 be significant and two identical functions can be merged.
774 If the ``local_unnamed_addr`` attribute is given, the address is known to
775 not be significant within the module.
777 If an explicit address space is not given, it will default to the program
778 address space from the :ref:`datalayout string<langref_datalayout>`.
782 define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass]
784 <ResultType> @<FunctionName> ([argument list])
785 [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs]
786 [section "name"] [comdat [($name)]] [align N] [gc] [prefix Constant]
787 [prologue Constant] [personality Constant] (!name !N)* { ... }
789 The argument list is a comma separated sequence of arguments where each
790 argument is of the following form:
794 <type> [parameter Attrs] [name]
802 Aliases, unlike function or variables, don't create any new data. They
803 are just a new symbol and metadata for an existing position.
805 Aliases have a name and an aliasee that is either a global value or a
808 Aliases may have an optional :ref:`linkage type <linkage>`, an optional
809 :ref:`runtime preemption specifier <runtime_preemption_model>`, an optional
810 :ref:`visibility style <visibility>`, an optional :ref:`DLL storage class
811 <dllstorageclass>` and an optional :ref:`tls model <tls_model>`.
815 @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee>
817 The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``,
818 ``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
819 might not correctly handle dropping a weak symbol that is aliased.
821 Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as
822 the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point
825 If the ``local_unnamed_addr`` attribute is given, the address is known to
826 not be significant within the module.
828 Since aliases are only a second name, some restrictions apply, of which
829 some can only be checked when producing an object file:
831 * The expression defining the aliasee must be computable at assembly
832 time. Since it is just a name, no relocations can be used.
834 * No alias in the expression can be weak as the possibility of the
835 intermediate alias being overridden cannot be represented in an
838 * No global value in the expression can be a declaration, since that
839 would require a relocation, which is not possible.
846 IFuncs, like as aliases, don't create any new data or func. They are just a new
847 symbol that dynamic linker resolves at runtime by calling a resolver function.
849 IFuncs have a name and a resolver that is a function called by dynamic linker
850 that returns address of another function associated with the name.
852 IFunc may have an optional :ref:`linkage type <linkage>` and an optional
853 :ref:`visibility style <visibility>`.
857 @<Name> = [Linkage] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver>
865 Comdat IR provides access to COFF and ELF object file COMDAT functionality.
867 Comdats have a name which represents the COMDAT key. All global objects that
868 specify this key will only end up in the final object file if the linker chooses
869 that key over some other key. Aliases are placed in the same COMDAT that their
870 aliasee computes to, if any.
872 Comdats have a selection kind to provide input on how the linker should
873 choose between keys in two different object files.
877 $<Name> = comdat SelectionKind
879 The selection kind must be one of the following:
882 The linker may choose any COMDAT key, the choice is arbitrary.
884 The linker may choose any COMDAT key but the sections must contain the
887 The linker will choose the section containing the largest COMDAT key.
889 The linker requires that only section with this COMDAT key exist.
891 The linker may choose any COMDAT key but the sections must contain the
894 Note that the Mach-O platform doesn't support COMDATs, and ELF and WebAssembly
895 only support ``any`` as a selection kind.
897 Here is an example of a COMDAT group where a function will only be selected if
898 the COMDAT key's section is the largest:
902 $foo = comdat largest
903 @foo = global i32 2, comdat($foo)
905 define void @bar() comdat($foo) {
909 As a syntactic sugar the ``$name`` can be omitted if the name is the same as
915 @foo = global i32 2, comdat
918 In a COFF object file, this will create a COMDAT section with selection kind
919 ``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol
920 and another COMDAT section with selection kind
921 ``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT
922 section and contains the contents of the ``@bar`` symbol.
924 There are some restrictions on the properties of the global object.
925 It, or an alias to it, must have the same name as the COMDAT group when
927 The contents and size of this object may be used during link-time to determine
928 which COMDAT groups get selected depending on the selection kind.
929 Because the name of the object must match the name of the COMDAT group, the
930 linkage of the global object must not be local; local symbols can get renamed
931 if a collision occurs in the symbol table.
933 The combined use of COMDATS and section attributes may yield surprising results.
940 @g1 = global i32 42, section "sec", comdat($foo)
941 @g2 = global i32 42, section "sec", comdat($bar)
943 From the object file perspective, this requires the creation of two sections
944 with the same name. This is necessary because both globals belong to different
945 COMDAT groups and COMDATs, at the object file level, are represented by
948 Note that certain IR constructs like global variables and functions may
949 create COMDATs in the object file in addition to any which are specified using
950 COMDAT IR. This arises when the code generator is configured to emit globals
951 in individual sections (e.g. when `-data-sections` or `-function-sections`
952 is supplied to `llc`).
954 .. _namedmetadatastructure:
959 Named metadata is a collection of metadata. :ref:`Metadata
960 nodes <metadata>` (but not metadata strings) are the only valid
961 operands for a named metadata.
963 #. Named metadata are represented as a string of characters with the
964 metadata prefix. The rules for metadata names are the same as for
965 identifiers, but quoted names are not allowed. ``"\xx"`` type escapes
966 are still valid, which allows any character to be part of a name.
970 ; Some unnamed metadata nodes, which are referenced by the named metadata.
975 !name = !{!0, !1, !2}
982 The return type and each parameter of a function type may have a set of
983 *parameter attributes* associated with them. Parameter attributes are
984 used to communicate additional information about the result or
985 parameters of a function. Parameter attributes are considered to be part
986 of the function, not of the function type, so functions with different
987 parameter attributes can have the same function type.
989 Parameter attributes are simple keywords that follow the type specified.
990 If multiple parameter attributes are needed, they are space separated.
995 declare i32 @printf(i8* noalias nocapture, ...)
996 declare i32 @atoi(i8 zeroext)
997 declare signext i8 @returns_signed_char()
999 Note that any attributes for the function result (``nounwind``,
1000 ``readonly``) come immediately after the argument list.
1002 Currently, only the following parameter attributes are defined:
1005 This indicates to the code generator that the parameter or return
1006 value should be zero-extended to the extent required by the target's
1007 ABI by the caller (for a parameter) or the callee (for a return value).
1009 This indicates to the code generator that the parameter or return
1010 value should be sign-extended to the extent required by the target's
1011 ABI (which is usually 32-bits) by the caller (for a parameter) or
1012 the callee (for a return value).
1014 This indicates that this parameter or return value should be treated
1015 in a special target-dependent fashion while emitting code for
1016 a function call or return (usually, by putting it in a register as
1017 opposed to memory, though some targets use it to distinguish between
1018 two different kinds of registers). Use of this attribute is
1020 ``byval`` or ``byval(<ty>)``
1021 This indicates that the pointer parameter should really be passed by
1022 value to the function. The attribute implies that a hidden copy of
1023 the pointee is made between the caller and the callee, so the callee
1024 is unable to modify the value in the caller. This attribute is only
1025 valid on LLVM pointer arguments. It is generally used to pass
1026 structs and arrays by value, but is also valid on pointers to
1027 scalars. The copy is considered to belong to the caller not the
1028 callee (for example, ``readonly`` functions should not write to
1029 ``byval`` parameters). This is not a valid attribute for return
1032 The byval attribute also supports an optional type argument, which must be
1033 the same as the pointee type of the argument.
1035 The byval attribute also supports specifying an alignment with the
1036 align attribute. It indicates the alignment of the stack slot to
1037 form and the known alignment of the pointer specified to the call
1038 site. If the alignment is not specified, then the code generator
1039 makes a target-specific assumption.
1045 The ``inalloca`` argument attribute allows the caller to take the
1046 address of outgoing stack arguments. An ``inalloca`` argument must
1047 be a pointer to stack memory produced by an ``alloca`` instruction.
1048 The alloca, or argument allocation, must also be tagged with the
1049 inalloca keyword. Only the last argument may have the ``inalloca``
1050 attribute, and that argument is guaranteed to be passed in memory.
1052 An argument allocation may be used by a call at most once because
1053 the call may deallocate it. The ``inalloca`` attribute cannot be
1054 used in conjunction with other attributes that affect argument
1055 storage, like ``inreg``, ``nest``, ``sret``, or ``byval``. The
1056 ``inalloca`` attribute also disables LLVM's implicit lowering of
1057 large aggregate return values, which means that frontend authors
1058 must lower them with ``sret`` pointers.
1060 When the call site is reached, the argument allocation must have
1061 been the most recent stack allocation that is still live, or the
1062 behavior is undefined. It is possible to allocate additional stack
1063 space after an argument allocation and before its call site, but it
1064 must be cleared off with :ref:`llvm.stackrestore
1065 <int_stackrestore>`.
1067 See :doc:`InAlloca` for more information on how to use this
1071 This indicates that the pointer parameter specifies the address of a
1072 structure that is the return value of the function in the source
1073 program. This pointer must be guaranteed by the caller to be valid:
1074 loads and stores to the structure may be assumed by the callee not
1075 to trap and to be properly aligned. This is not a valid attribute
1081 This indicates that the pointer value may be assumed by the optimizer to
1082 have the specified alignment. If the pointer value does not have the
1083 specified alignment, behavior is undefined.
1085 Note that this attribute has additional semantics when combined with the
1086 ``byval`` attribute, which are documented there.
1091 This indicates that objects accessed via pointer values
1092 :ref:`based <pointeraliasing>` on the argument or return value are not also
1093 accessed, during the execution of the function, via pointer values not
1094 *based* on the argument or return value. The attribute on a return value
1095 also has additional semantics described below. The caller shares the
1096 responsibility with the callee for ensuring that these requirements are met.
1097 For further details, please see the discussion of the NoAlias response in
1098 :ref:`alias analysis <Must, May, or No>`.
1100 Note that this definition of ``noalias`` is intentionally similar
1101 to the definition of ``restrict`` in C99 for function arguments.
1103 For function return values, C99's ``restrict`` is not meaningful,
1104 while LLVM's ``noalias`` is. Furthermore, the semantics of the ``noalias``
1105 attribute on return values are stronger than the semantics of the attribute
1106 when used on function arguments. On function return values, the ``noalias``
1107 attribute indicates that the function acts like a system memory allocation
1108 function, returning a pointer to allocated storage disjoint from the
1109 storage for any other object accessible to the caller.
1112 This indicates that the callee does not make any copies of the
1113 pointer that outlive the callee itself. This is not a valid
1114 attribute for return values. Addresses used in volatile operations
1115 are considered to be captured.
1120 This indicates that the pointer parameter can be excised using the
1121 :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
1122 attribute for return values and can only be applied to one parameter.
1125 This indicates that the function always returns the argument as its return
1126 value. This is a hint to the optimizer and code generator used when
1127 generating the caller, allowing value propagation, tail call optimization,
1128 and omission of register saves and restores in some cases; it is not
1129 checked or enforced when generating the callee. The parameter and the
1130 function return type must be valid operands for the
1131 :ref:`bitcast instruction <i_bitcast>`. This is not a valid attribute for
1132 return values and can only be applied to one parameter.
1135 This indicates that the parameter or return pointer is not null. This
1136 attribute may only be applied to pointer typed parameters. This is not
1137 checked or enforced by LLVM; if the parameter or return pointer is null,
1138 the behavior is undefined.
1140 ``dereferenceable(<n>)``
1141 This indicates that the parameter or return pointer is dereferenceable. This
1142 attribute may only be applied to pointer typed parameters. A pointer that
1143 is dereferenceable can be loaded from speculatively without a risk of
1144 trapping. The number of bytes known to be dereferenceable must be provided
1145 in parentheses. It is legal for the number of bytes to be less than the
1146 size of the pointee type. The ``nonnull`` attribute does not imply
1147 dereferenceability (consider a pointer to one element past the end of an
1148 array), however ``dereferenceable(<n>)`` does imply ``nonnull`` in
1149 ``addrspace(0)`` (which is the default address space).
1151 ``dereferenceable_or_null(<n>)``
1152 This indicates that the parameter or return value isn't both
1153 non-null and non-dereferenceable (up to ``<n>`` bytes) at the same
1154 time. All non-null pointers tagged with
1155 ``dereferenceable_or_null(<n>)`` are ``dereferenceable(<n>)``.
1156 For address space 0 ``dereferenceable_or_null(<n>)`` implies that
1157 a pointer is exactly one of ``dereferenceable(<n>)`` or ``null``,
1158 and in other address spaces ``dereferenceable_or_null(<n>)``
1159 implies that a pointer is at least one of ``dereferenceable(<n>)``
1160 or ``null`` (i.e. it may be both ``null`` and
1161 ``dereferenceable(<n>)``). This attribute may only be applied to
1162 pointer typed parameters.
1165 This indicates that the parameter is the self/context parameter. This is not
1166 a valid attribute for return values and can only be applied to one
1170 This attribute is motivated to model and optimize Swift error handling. It
1171 can be applied to a parameter with pointer to pointer type or a
1172 pointer-sized alloca. At the call site, the actual argument that corresponds
1173 to a ``swifterror`` parameter has to come from a ``swifterror`` alloca or
1174 the ``swifterror`` parameter of the caller. A ``swifterror`` value (either
1175 the parameter or the alloca) can only be loaded and stored from, or used as
1176 a ``swifterror`` argument. This is not a valid attribute for return values
1177 and can only be applied to one parameter.
1179 These constraints allow the calling convention to optimize access to
1180 ``swifterror`` variables by associating them with a specific register at
1181 call boundaries rather than placing them in memory. Since this does change
1182 the calling convention, a function which uses the ``swifterror`` attribute
1183 on a parameter is not ABI-compatible with one which does not.
1185 These constraints also allow LLVM to assume that a ``swifterror`` argument
1186 does not alias any other memory visible within a function and that a
1187 ``swifterror`` alloca passed as an argument does not escape.
1190 This indicates the parameter is required to be an immediate
1191 value. This must be a trivial immediate integer or floating-point
1192 constant. Undef or constant expressions are not valid. This is
1193 only valid on intrinsic declarations and cannot be applied to a
1194 call site or arbitrary function.
1198 Garbage Collector Strategy Names
1199 --------------------------------
1201 Each function may specify a garbage collector strategy name, which is simply a
1204 .. code-block:: llvm
1206 define void @f() gc "name" { ... }
1208 The supported values of *name* includes those :ref:`built in to LLVM
1209 <builtin-gc-strategies>` and any provided by loaded plugins. Specifying a GC
1210 strategy will cause the compiler to alter its output in order to support the
1211 named garbage collection algorithm. Note that LLVM itself does not contain a
1212 garbage collector, this functionality is restricted to generating machine code
1213 which can interoperate with a collector provided externally.
1220 Prefix data is data associated with a function which the code
1221 generator will emit immediately before the function's entrypoint.
1222 The purpose of this feature is to allow frontends to associate
1223 language-specific runtime metadata with specific functions and make it
1224 available through the function pointer while still allowing the
1225 function pointer to be called.
1227 To access the data for a given function, a program may bitcast the
1228 function pointer to a pointer to the constant's type and dereference
1229 index -1. This implies that the IR symbol points just past the end of
1230 the prefix data. For instance, take the example of a function annotated
1231 with a single ``i32``,
1233 .. code-block:: llvm
1235 define void @f() prefix i32 123 { ... }
1237 The prefix data can be referenced as,
1239 .. code-block:: llvm
1241 %0 = bitcast void* () @f to i32*
1242 %a = getelementptr inbounds i32, i32* %0, i32 -1
1243 %b = load i32, i32* %a
1245 Prefix data is laid out as if it were an initializer for a global variable
1246 of the prefix data's type. The function will be placed such that the
1247 beginning of the prefix data is aligned. This means that if the size
1248 of the prefix data is not a multiple of the alignment size, the
1249 function's entrypoint will not be aligned. If alignment of the
1250 function's entrypoint is desired, padding must be added to the prefix
1253 A function may have prefix data but no body. This has similar semantics
1254 to the ``available_externally`` linkage in that the data may be used by the
1255 optimizers but will not be emitted in the object file.
1262 The ``prologue`` attribute allows arbitrary code (encoded as bytes) to
1263 be inserted prior to the function body. This can be used for enabling
1264 function hot-patching and instrumentation.
1266 To maintain the semantics of ordinary function calls, the prologue data must
1267 have a particular format. Specifically, it must begin with a sequence of
1268 bytes which decode to a sequence of machine instructions, valid for the
1269 module's target, which transfer control to the point immediately succeeding
1270 the prologue data, without performing any other visible action. This allows
1271 the inliner and other passes to reason about the semantics of the function
1272 definition without needing to reason about the prologue data. Obviously this
1273 makes the format of the prologue data highly target dependent.
1275 A trivial example of valid prologue data for the x86 architecture is ``i8 144``,
1276 which encodes the ``nop`` instruction:
1278 .. code-block:: text
1280 define void @f() prologue i8 144 { ... }
1282 Generally prologue data can be formed by encoding a relative branch instruction
1283 which skips the metadata, as in this example of valid prologue data for the
1284 x86_64 architecture, where the first two bytes encode ``jmp .+10``:
1286 .. code-block:: text
1288 %0 = type <{ i8, i8, i8* }>
1290 define void @f() prologue %0 <{ i8 235, i8 8, i8* @md}> { ... }
1292 A function may have prologue data but no body. This has similar semantics
1293 to the ``available_externally`` linkage in that the data may be used by the
1294 optimizers but will not be emitted in the object file.
1298 Personality Function
1299 --------------------
1301 The ``personality`` attribute permits functions to specify what function
1302 to use for exception handling.
1309 Attribute groups are groups of attributes that are referenced by objects within
1310 the IR. They are important for keeping ``.ll`` files readable, because a lot of
1311 functions will use the same set of attributes. In the degenerative case of a
1312 ``.ll`` file that corresponds to a single ``.c`` file, the single attribute
1313 group will capture the important command line flags used to build that file.
1315 An attribute group is a module-level object. To use an attribute group, an
1316 object references the attribute group's ID (e.g. ``#37``). An object may refer
1317 to more than one attribute group. In that situation, the attributes from the
1318 different groups are merged.
1320 Here is an example of attribute groups for a function that should always be
1321 inlined, has a stack alignment of 4, and which shouldn't use SSE instructions:
1323 .. code-block:: llvm
1325 ; Target-independent attributes:
1326 attributes #0 = { alwaysinline alignstack=4 }
1328 ; Target-dependent attributes:
1329 attributes #1 = { "no-sse" }
1331 ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".
1332 define void @f() #0 #1 { ... }
1339 Function attributes are set to communicate additional information about
1340 a function. Function attributes are considered to be part of the
1341 function, not of the function type, so functions with different function
1342 attributes can have the same function type.
1344 Function attributes are simple keywords that follow the type specified.
1345 If multiple attributes are needed, they are space separated. For
1348 .. code-block:: llvm
1350 define void @f() noinline { ... }
1351 define void @f() alwaysinline { ... }
1352 define void @f() alwaysinline optsize { ... }
1353 define void @f() optsize { ... }
1356 This attribute indicates that, when emitting the prologue and
1357 epilogue, the backend should forcibly align the stack pointer.
1358 Specify the desired alignment, which must be a power of two, in
1360 ``allocsize(<EltSizeParam>[, <NumEltsParam>])``
1361 This attribute indicates that the annotated function will always return at
1362 least a given number of bytes (or null). Its arguments are zero-indexed
1363 parameter numbers; if one argument is provided, then it's assumed that at
1364 least ``CallSite.Args[EltSizeParam]`` bytes will be available at the
1365 returned pointer. If two are provided, then it's assumed that
1366 ``CallSite.Args[EltSizeParam] * CallSite.Args[NumEltsParam]`` bytes are
1367 available. The referenced parameters must be integer types. No assumptions
1368 are made about the contents of the returned block of memory.
1370 This attribute indicates that the inliner should attempt to inline
1371 this function into callers whenever possible, ignoring any active
1372 inlining size threshold for this caller.
1374 This indicates that the callee function at a call site should be
1375 recognized as a built-in function, even though the function's declaration
1376 uses the ``nobuiltin`` attribute. This is only valid at call sites for
1377 direct calls to functions that are declared with the ``nobuiltin``
1380 This attribute indicates that this function is rarely called. When
1381 computing edge weights, basic blocks post-dominated by a cold
1382 function call are also considered to be cold; and, thus, given low
1385 In some parallel execution models, there exist operations that cannot be
1386 made control-dependent on any additional values. We call such operations
1387 ``convergent``, and mark them with this attribute.
1389 The ``convergent`` attribute may appear on functions or call/invoke
1390 instructions. When it appears on a function, it indicates that calls to
1391 this function should not be made control-dependent on additional values.
1392 For example, the intrinsic ``llvm.nvvm.barrier0`` is ``convergent``, so
1393 calls to this intrinsic cannot be made control-dependent on additional
1396 When it appears on a call/invoke, the ``convergent`` attribute indicates
1397 that we should treat the call as though we're calling a convergent
1398 function. This is particularly useful on indirect calls; without this we
1399 may treat such calls as though the target is non-convergent.
1401 The optimizer may remove the ``convergent`` attribute on functions when it
1402 can prove that the function does not execute any convergent operations.
1403 Similarly, the optimizer may remove ``convergent`` on calls/invokes when it
1404 can prove that the call/invoke cannot call a convergent function.
1405 ``inaccessiblememonly``
1406 This attribute indicates that the function may only access memory that
1407 is not accessible by the module being compiled. This is a weaker form
1408 of ``readnone``. If the function reads or writes other memory, the
1409 behavior is undefined.
1410 ``inaccessiblemem_or_argmemonly``
1411 This attribute indicates that the function may only access memory that is
1412 either not accessible by the module being compiled, or is pointed to
1413 by its pointer arguments. This is a weaker form of ``argmemonly``. If the
1414 function reads or writes other memory, the behavior is undefined.
1416 This attribute indicates that the source code contained a hint that
1417 inlining this function is desirable (such as the "inline" keyword in
1418 C/C++). It is just a hint; it imposes no requirements on the
1421 This attribute indicates that the function should be added to a
1422 jump-instruction table at code-generation time, and that all address-taken
1423 references to this function should be replaced with a reference to the
1424 appropriate jump-instruction-table function pointer. Note that this creates
1425 a new pointer for the original function, which means that code that depends
1426 on function-pointer identity can break. So, any function annotated with
1427 ``jumptable`` must also be ``unnamed_addr``.
1429 This attribute suggests that optimization passes and code generator
1430 passes make choices that keep the code size of this function as small
1431 as possible and perform optimizations that may sacrifice runtime
1432 performance in order to minimize the size of the generated code.
1434 This attribute disables prologue / epilogue emission for the
1435 function. This can have very system-specific consequences.
1437 When this attribute is set to true, the jump tables and lookup tables that
1438 can be generated from a switch case lowering are disabled.
1440 This indicates that the callee function at a call site is not recognized as
1441 a built-in function. LLVM will retain the original call and not replace it
1442 with equivalent code based on the semantics of the built-in function, unless
1443 the call site uses the ``builtin`` attribute. This is valid at call sites
1444 and on function declarations and definitions.
1446 This attribute indicates that calls to the function cannot be
1447 duplicated. A call to a ``noduplicate`` function may be moved
1448 within its parent function, but may not be duplicated within
1449 its parent function.
1451 A function containing a ``noduplicate`` call may still
1452 be an inlining candidate, provided that the call is not
1453 duplicated by inlining. That implies that the function has
1454 internal linkage and only has one call site, so the original
1455 call is dead after inlining.
1457 This attributes disables implicit floating-point instructions.
1459 This attribute indicates that the inliner should never inline this
1460 function in any situation. This attribute may not be used together
1461 with the ``alwaysinline`` attribute.
1463 This attribute suppresses lazy symbol binding for the function. This
1464 may make calls to the function faster, at the cost of extra program
1465 startup time if the function is not called during program startup.
1467 This attribute indicates that the code generator should not use a
1468 red zone, even if the target-specific ABI normally permits it.
1469 ``indirect-tls-seg-refs``
1470 This attribute indicates that the code generator should not use
1471 direct TLS access through segment registers, even if the
1472 target-specific ABI normally permits it.
1474 This function attribute indicates that the function never returns
1475 normally. This produces undefined behavior at runtime if the
1476 function ever does dynamically return.
1478 This function attribute indicates that the function does not call itself
1479 either directly or indirectly down any possible call path. This produces
1480 undefined behavior at runtime if the function ever does recurse.
1482 This function attribute indicates that the function never raises an
1483 exception. If the function does raise an exception, its runtime
1484 behavior is undefined. However, functions marked nounwind may still
1485 trap or generate asynchronous exceptions. Exception handling schemes
1486 that are recognized by LLVM to handle asynchronous exceptions, such
1487 as SEH, will still provide their implementation defined semantics.
1488 ``"null-pointer-is-valid"``
1489 If ``"null-pointer-is-valid"`` is set to ``"true"``, then ``null`` address
1490 in address-space 0 is considered to be a valid address for memory loads and
1491 stores. Any analysis or optimization should not treat dereferencing a
1492 pointer to ``null`` as undefined behavior in this function.
1493 Note: Comparing address of a global variable to ``null`` may still
1494 evaluate to false because of a limitation in querying this attribute inside
1495 constant expressions.
1497 This attribute indicates that this function should be optimized
1498 for maximum fuzzing signal.
1500 This function attribute indicates that most optimization passes will skip
1501 this function, with the exception of interprocedural optimization passes.
1502 Code generation defaults to the "fast" instruction selector.
1503 This attribute cannot be used together with the ``alwaysinline``
1504 attribute; this attribute is also incompatible
1505 with the ``minsize`` attribute and the ``optsize`` attribute.
1507 This attribute requires the ``noinline`` attribute to be specified on
1508 the function as well, so the function is never inlined into any caller.
1509 Only functions with the ``alwaysinline`` attribute are valid
1510 candidates for inlining into the body of this function.
1512 This attribute suggests that optimization passes and code generator
1513 passes make choices that keep the code size of this function low,
1514 and otherwise do optimizations specifically to reduce code size as
1515 long as they do not significantly impact runtime performance.
1516 ``"patchable-function"``
1517 This attribute tells the code generator that the code
1518 generated for this function needs to follow certain conventions that
1519 make it possible for a runtime function to patch over it later.
1520 The exact effect of this attribute depends on its string value,
1521 for which there currently is one legal possibility:
1523 * ``"prologue-short-redirect"`` - This style of patchable
1524 function is intended to support patching a function prologue to
1525 redirect control away from the function in a thread safe
1526 manner. It guarantees that the first instruction of the
1527 function will be large enough to accommodate a short jump
1528 instruction, and will be sufficiently aligned to allow being
1529 fully changed via an atomic compare-and-swap instruction.
1530 While the first requirement can be satisfied by inserting large
1531 enough NOP, LLVM can and will try to re-purpose an existing
1532 instruction (i.e. one that would have to be emitted anyway) as
1533 the patchable instruction larger than a short jump.
1535 ``"prologue-short-redirect"`` is currently only supported on
1538 This attribute by itself does not imply restrictions on
1539 inter-procedural optimizations. All of the semantic effects the
1540 patching may have to be separately conveyed via the linkage type.
1542 This attribute indicates that the function will trigger a guard region
1543 in the end of the stack. It ensures that accesses to the stack must be
1544 no further apart than the size of the guard region to a previous
1545 access of the stack. It takes one required string value, the name of
1546 the stack probing function that will be called.
1548 If a function that has a ``"probe-stack"`` attribute is inlined into
1549 a function with another ``"probe-stack"`` attribute, the resulting
1550 function has the ``"probe-stack"`` attribute of the caller. If a
1551 function that has a ``"probe-stack"`` attribute is inlined into a
1552 function that has no ``"probe-stack"`` attribute at all, the resulting
1553 function has the ``"probe-stack"`` attribute of the callee.
1555 On a function, this attribute indicates that the function computes its
1556 result (or decides to unwind an exception) based strictly on its arguments,
1557 without dereferencing any pointer arguments or otherwise accessing
1558 any mutable state (e.g. memory, control registers, etc) visible to
1559 caller functions. It does not write through any pointer arguments
1560 (including ``byval`` arguments) and never changes any state visible
1561 to callers. This means while it cannot unwind exceptions by calling
1562 the ``C++`` exception throwing methods (since they write to memory), there may
1563 be non-``C++`` mechanisms that throw exceptions without writing to LLVM
1566 On an argument, this attribute indicates that the function does not
1567 dereference that pointer argument, even though it may read or write the
1568 memory that the pointer points to if accessed through other pointers.
1570 If a readnone function reads or writes memory visible to the program, or
1571 has other side-effects, the behavior is undefined. If a function reads from
1572 or writes to a readnone pointer argument, the behavior is undefined.
1574 On a function, this attribute indicates that the function does not write
1575 through any pointer arguments (including ``byval`` arguments) or otherwise
1576 modify any state (e.g. memory, control registers, etc) visible to
1577 caller functions. It may dereference pointer arguments and read
1578 state that may be set in the caller. A readonly function always
1579 returns the same value (or unwinds an exception identically) when
1580 called with the same set of arguments and global state. This means while it
1581 cannot unwind exceptions by calling the ``C++`` exception throwing methods
1582 (since they write to memory), there may be non-``C++`` mechanisms that throw
1583 exceptions without writing to LLVM visible memory.
1585 On an argument, this attribute indicates that the function does not write
1586 through this pointer argument, even though it may write to the memory that
1587 the pointer points to.
1589 If a readonly function writes memory visible to the program, or
1590 has other side-effects, the behavior is undefined. If a function writes to
1591 a readonly pointer argument, the behavior is undefined.
1592 ``"stack-probe-size"``
1593 This attribute controls the behavior of stack probes: either
1594 the ``"probe-stack"`` attribute, or ABI-required stack probes, if any.
1595 It defines the size of the guard region. It ensures that if the function
1596 may use more stack space than the size of the guard region, stack probing
1597 sequence will be emitted. It takes one required integer value, which
1600 If a function that has a ``"stack-probe-size"`` attribute is inlined into
1601 a function with another ``"stack-probe-size"`` attribute, the resulting
1602 function has the ``"stack-probe-size"`` attribute that has the lower
1603 numeric value. If a function that has a ``"stack-probe-size"`` attribute is
1604 inlined into a function that has no ``"stack-probe-size"`` attribute
1605 at all, the resulting function has the ``"stack-probe-size"`` attribute
1607 ``"no-stack-arg-probe"``
1608 This attribute disables ABI-required stack probes, if any.
1610 On a function, this attribute indicates that the function may write to but
1611 does not read from memory.
1613 On an argument, this attribute indicates that the function may write to but
1614 does not read through this pointer argument (even though it may read from
1615 the memory that the pointer points to).
1617 If a writeonly function reads memory visible to the program, or
1618 has other side-effects, the behavior is undefined. If a function reads
1619 from a writeonly pointer argument, the behavior is undefined.
1621 This attribute indicates that the only memory accesses inside function are
1622 loads and stores from objects pointed to by its pointer-typed arguments,
1623 with arbitrary offsets. Or in other words, all memory operations in the
1624 function can refer to memory only using pointers based on its function
1627 Note that ``argmemonly`` can be used together with ``readonly`` attribute
1628 in order to specify that function reads only from its arguments.
1630 If an argmemonly function reads or writes memory other than the pointer
1631 arguments, or has other side-effects, the behavior is undefined.
1633 This attribute indicates that this function can return twice. The C
1634 ``setjmp`` is an example of such a function. The compiler disables
1635 some optimizations (like tail calls) in the caller of these
1638 This attribute indicates that
1639 `SafeStack <http://clang.llvm.org/docs/SafeStack.html>`_
1640 protection is enabled for this function.
1642 If a function that has a ``safestack`` attribute is inlined into a
1643 function that doesn't have a ``safestack`` attribute or which has an
1644 ``ssp``, ``sspstrong`` or ``sspreq`` attribute, then the resulting
1645 function will have a ``safestack`` attribute.
1646 ``sanitize_address``
1647 This attribute indicates that AddressSanitizer checks
1648 (dynamic address safety analysis) are enabled for this function.
1650 This attribute indicates that MemorySanitizer checks (dynamic detection
1651 of accesses to uninitialized memory) are enabled for this function.
1653 This attribute indicates that ThreadSanitizer checks
1654 (dynamic thread safety analysis) are enabled for this function.
1655 ``sanitize_hwaddress``
1656 This attribute indicates that HWAddressSanitizer checks
1657 (dynamic address safety analysis based on tagged pointers) are enabled for
1659 ``speculative_load_hardening``
1660 This attribute indicates that
1661 `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
1662 should be enabled for the function body.
1664 Speculative Load Hardening is a best-effort mitigation against
1665 information leak attacks that make use of control flow
1666 miss-speculation - specifically miss-speculation of whether a branch
1667 is taken or not. Typically vulnerabilities enabling such attacks are
1668 classified as "Spectre variant #1". Notably, this does not attempt to
1669 mitigate against miss-speculation of branch target, classified as
1670 "Spectre variant #2" vulnerabilities.
1672 When inlining, the attribute is sticky. Inlining a function that carries
1673 this attribute will cause the caller to gain the attribute. This is intended
1674 to provide a maximally conservative model where the code in a function
1675 annotated with this attribute will always (even after inlining) end up
1678 This function attribute indicates that the function does not have any
1679 effects besides calculating its result and does not have undefined behavior.
1680 Note that ``speculatable`` is not enough to conclude that along any
1681 particular execution path the number of calls to this function will not be
1682 externally observable. This attribute is only valid on functions
1683 and declarations, not on individual call sites. If a function is
1684 incorrectly marked as speculatable and really does exhibit
1685 undefined behavior, the undefined behavior may be observed even
1686 if the call site is dead code.
1689 This attribute indicates that the function should emit a stack
1690 smashing protector. It is in the form of a "canary" --- a random value
1691 placed on the stack before the local variables that's checked upon
1692 return from the function to see if it has been overwritten. A
1693 heuristic is used to determine if a function needs stack protectors
1694 or not. The heuristic used will enable protectors for functions with:
1696 - Character arrays larger than ``ssp-buffer-size`` (default 8).
1697 - Aggregates containing character arrays larger than ``ssp-buffer-size``.
1698 - Calls to alloca() with variable sizes or constant sizes greater than
1699 ``ssp-buffer-size``.
1701 Variables that are identified as requiring a protector will be arranged
1702 on the stack such that they are adjacent to the stack protector guard.
1704 If a function that has an ``ssp`` attribute is inlined into a
1705 function that doesn't have an ``ssp`` attribute, then the resulting
1706 function will have an ``ssp`` attribute.
1708 This attribute indicates that the function should *always* emit a
1709 stack smashing protector. This overrides the ``ssp`` function
1712 Variables that are identified as requiring a protector will be arranged
1713 on the stack such that they are adjacent to the stack protector guard.
1714 The specific layout rules are:
1716 #. Large arrays and structures containing large arrays
1717 (``>= ssp-buffer-size``) are closest to the stack protector.
1718 #. Small arrays and structures containing small arrays
1719 (``< ssp-buffer-size``) are 2nd closest to the protector.
1720 #. Variables that have had their address taken are 3rd closest to the
1723 If a function that has an ``sspreq`` attribute is inlined into a
1724 function that doesn't have an ``sspreq`` attribute or which has an
1725 ``ssp`` or ``sspstrong`` attribute, then the resulting function will have
1726 an ``sspreq`` attribute.
1728 This attribute indicates that the function should emit a stack smashing
1729 protector. This attribute causes a strong heuristic to be used when
1730 determining if a function needs stack protectors. The strong heuristic
1731 will enable protectors for functions with:
1733 - Arrays of any size and type
1734 - Aggregates containing an array of any size and type.
1735 - Calls to alloca().
1736 - Local variables that have had their address taken.
1738 Variables that are identified as requiring a protector will be arranged
1739 on the stack such that they are adjacent to the stack protector guard.
1740 The specific layout rules are:
1742 #. Large arrays and structures containing large arrays
1743 (``>= ssp-buffer-size``) are closest to the stack protector.
1744 #. Small arrays and structures containing small arrays
1745 (``< ssp-buffer-size``) are 2nd closest to the protector.
1746 #. Variables that have had their address taken are 3rd closest to the
1749 This overrides the ``ssp`` function attribute.
1751 If a function that has an ``sspstrong`` attribute is inlined into a
1752 function that doesn't have an ``sspstrong`` attribute, then the
1753 resulting function will have an ``sspstrong`` attribute.
1755 This attribute indicates that the function was called from a scope that
1756 requires strict floating-point semantics. LLVM will not attempt any
1757 optimizations that require assumptions about the floating-point rounding
1758 mode or that might alter the state of floating-point status flags that
1759 might otherwise be set or cleared by calling this function.
1761 This attribute indicates that the function will delegate to some other
1762 function with a tail call. The prototype of a thunk should not be used for
1763 optimization purposes. The caller is expected to cast the thunk prototype to
1764 match the thunk target prototype.
1766 This attribute indicates that the ABI being targeted requires that
1767 an unwind table entry be produced for this function even if we can
1768 show that no exceptions passes by it. This is normally the case for
1769 the ELF x86-64 abi, but it can be disabled for some compilation
1772 This attribute indicates that no control-flow check will be performed on
1773 the attributed entity. It disables -fcf-protection=<> for a specific
1774 entity to fine grain the HW control flow protection mechanism. The flag
1775 is target independent and currently appertains to a function or function
1778 This attribute indicates that the ShadowCallStack checks are enabled for
1779 the function. The instrumentation checks that the return address for the
1780 function has not changed between the function prolog and eiplog. It is
1781 currently x86_64-specific.
1788 Attributes may be set to communicate additional information about a global variable.
1789 Unlike :ref:`function attributes <fnattrs>`, attributes on a global variable
1790 are grouped into a single :ref:`attribute group <attrgrp>`.
1797 Operand bundles are tagged sets of SSA values that can be associated
1798 with certain LLVM instructions (currently only ``call`` s and
1799 ``invoke`` s). In a way they are like metadata, but dropping them is
1800 incorrect and will change program semantics.
1804 operand bundle set ::= '[' operand bundle (, operand bundle )* ']'
1805 operand bundle ::= tag '(' [ bundle operand ] (, bundle operand )* ')'
1806 bundle operand ::= SSA value
1807 tag ::= string constant
1809 Operand bundles are **not** part of a function's signature, and a
1810 given function may be called from multiple places with different kinds
1811 of operand bundles. This reflects the fact that the operand bundles
1812 are conceptually a part of the ``call`` (or ``invoke``), not the
1813 callee being dispatched to.
1815 Operand bundles are a generic mechanism intended to support
1816 runtime-introspection-like functionality for managed languages. While
1817 the exact semantics of an operand bundle depend on the bundle tag,
1818 there are certain limitations to how much the presence of an operand
1819 bundle can influence the semantics of a program. These restrictions
1820 are described as the semantics of an "unknown" operand bundle. As
1821 long as the behavior of an operand bundle is describable within these
1822 restrictions, LLVM does not need to have special knowledge of the
1823 operand bundle to not miscompile programs containing it.
1825 - The bundle operands for an unknown operand bundle escape in unknown
1826 ways before control is transferred to the callee or invokee.
1827 - Calls and invokes with operand bundles have unknown read / write
1828 effect on the heap on entry and exit (even if the call target is
1829 ``readnone`` or ``readonly``), unless they're overridden with
1830 callsite specific attributes.
1831 - An operand bundle at a call site cannot change the implementation
1832 of the called function. Inter-procedural optimizations work as
1833 usual as long as they take into account the first two properties.
1835 More specific types of operand bundles are described below.
1837 .. _deopt_opbundles:
1839 Deoptimization Operand Bundles
1840 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1842 Deoptimization operand bundles are characterized by the ``"deopt"``
1843 operand bundle tag. These operand bundles represent an alternate
1844 "safe" continuation for the call site they're attached to, and can be
1845 used by a suitable runtime to deoptimize the compiled frame at the
1846 specified call site. There can be at most one ``"deopt"`` operand
1847 bundle attached to a call site. Exact details of deoptimization is
1848 out of scope for the language reference, but it usually involves
1849 rewriting a compiled frame into a set of interpreted frames.
1851 From the compiler's perspective, deoptimization operand bundles make
1852 the call sites they're attached to at least ``readonly``. They read
1853 through all of their pointer typed operands (even if they're not
1854 otherwise escaped) and the entire visible heap. Deoptimization
1855 operand bundles do not capture their operands except during
1856 deoptimization, in which case control will not be returned to the
1859 The inliner knows how to inline through calls that have deoptimization
1860 operand bundles. Just like inlining through a normal call site
1861 involves composing the normal and exceptional continuations, inlining
1862 through a call site with a deoptimization operand bundle needs to
1863 appropriately compose the "safe" deoptimization continuation. The
1864 inliner does this by prepending the parent's deoptimization
1865 continuation to every deoptimization continuation in the inlined body.
1866 E.g. inlining ``@f`` into ``@g`` in the following example
1868 .. code-block:: llvm
1871 call void @x() ;; no deopt state
1872 call void @y() [ "deopt"(i32 10) ]
1873 call void @y() [ "deopt"(i32 10), "unknown"(i8* null) ]
1878 call void @f() [ "deopt"(i32 20) ]
1884 .. code-block:: llvm
1887 call void @x() ;; still no deopt state
1888 call void @y() [ "deopt"(i32 20, i32 10) ]
1889 call void @y() [ "deopt"(i32 20, i32 10), "unknown"(i8* null) ]
1893 It is the frontend's responsibility to structure or encode the
1894 deoptimization state in a way that syntactically prepending the
1895 caller's deoptimization state to the callee's deoptimization state is
1896 semantically equivalent to composing the caller's deoptimization
1897 continuation after the callee's deoptimization continuation.
1901 Funclet Operand Bundles
1902 ^^^^^^^^^^^^^^^^^^^^^^^
1904 Funclet operand bundles are characterized by the ``"funclet"``
1905 operand bundle tag. These operand bundles indicate that a call site
1906 is within a particular funclet. There can be at most one
1907 ``"funclet"`` operand bundle attached to a call site and it must have
1908 exactly one bundle operand.
1910 If any funclet EH pads have been "entered" but not "exited" (per the
1911 `description in the EH doc\ <ExceptionHandling.html#wineh-constraints>`_),
1912 it is undefined behavior to execute a ``call`` or ``invoke`` which:
1914 * does not have a ``"funclet"`` bundle and is not a ``call`` to a nounwind
1916 * has a ``"funclet"`` bundle whose operand is not the most-recently-entered
1917 not-yet-exited funclet EH pad.
1919 Similarly, if no funclet EH pads have been entered-but-not-yet-exited,
1920 executing a ``call`` or ``invoke`` with a ``"funclet"`` bundle is undefined behavior.
1922 GC Transition Operand Bundles
1923 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1925 GC transition operand bundles are characterized by the
1926 ``"gc-transition"`` operand bundle tag. These operand bundles mark a
1927 call as a transition between a function with one GC strategy to a
1928 function with a different GC strategy. If coordinating the transition
1929 between GC strategies requires additional code generation at the call
1930 site, these bundles may contain any values that are needed by the
1931 generated code. For more details, see :ref:`GC Transitions
1932 <gc_transition_args>`.
1936 Module-Level Inline Assembly
1937 ----------------------------
1939 Modules may contain "module-level inline asm" blocks, which corresponds
1940 to the GCC "file scope inline asm" blocks. These blocks are internally
1941 concatenated by LLVM and treated as a single unit, but may be separated
1942 in the ``.ll`` file if desired. The syntax is very simple:
1944 .. code-block:: llvm
1946 module asm "inline asm code goes here"
1947 module asm "more can go here"
1949 The strings can contain any character by escaping non-printable
1950 characters. The escape sequence used is simply "\\xx" where "xx" is the
1951 two digit hex code for the number.
1953 Note that the assembly string *must* be parseable by LLVM's integrated assembler
1954 (unless it is disabled), even when emitting a ``.s`` file.
1956 .. _langref_datalayout:
1961 A module may specify a target specific data layout string that specifies
1962 how data is to be laid out in memory. The syntax for the data layout is
1965 .. code-block:: llvm
1967 target datalayout = "layout specification"
1969 The *layout specification* consists of a list of specifications
1970 separated by the minus sign character ('-'). Each specification starts
1971 with a letter and may include other information after the letter to
1972 define some aspect of the data layout. The specifications accepted are
1976 Specifies that the target lays out data in big-endian form. That is,
1977 the bits with the most significance have the lowest address
1980 Specifies that the target lays out data in little-endian form. That
1981 is, the bits with the least significance have the lowest address
1984 Specifies the natural alignment of the stack in bits. Alignment
1985 promotion of stack variables is limited to the natural stack
1986 alignment to avoid dynamic stack realignment. The stack alignment
1987 must be a multiple of 8-bits. If omitted, the natural stack
1988 alignment defaults to "unspecified", which does not prevent any
1989 alignment promotions.
1990 ``P<address space>``
1991 Specifies the address space that corresponds to program memory.
1992 Harvard architectures can use this to specify what space LLVM
1993 should place things such as functions into. If omitted, the
1994 program memory space defaults to the default address space of 0,
1995 which corresponds to a Von Neumann architecture that has code
1996 and data in the same space.
1997 ``A<address space>``
1998 Specifies the address space of objects created by '``alloca``'.
1999 Defaults to the default address space of 0.
2000 ``p[n]:<size>:<abi>:<pref>:<idx>``
2001 This specifies the *size* of a pointer and its ``<abi>`` and
2002 ``<pref>``\erred alignments for address space ``n``. The fourth parameter
2003 ``<idx>`` is a size of index that used for address calculation. If not
2004 specified, the default index size is equal to the pointer size. All sizes
2005 are in bits. The address space, ``n``, is optional, and if not specified,
2006 denotes the default address space 0. The value of ``n`` must be
2007 in the range [1,2^23).
2008 ``i<size>:<abi>:<pref>``
2009 This specifies the alignment for an integer type of a given bit
2010 ``<size>``. The value of ``<size>`` must be in the range [1,2^23).
2011 ``v<size>:<abi>:<pref>``
2012 This specifies the alignment for a vector type of a given bit
2014 ``f<size>:<abi>:<pref>``
2015 This specifies the alignment for a floating-point type of a given bit
2016 ``<size>``. Only values of ``<size>`` that are supported by the target
2017 will work. 32 (float) and 64 (double) are supported on all targets; 80
2018 or 128 (different flavors of long double) are also supported on some
2021 This specifies the alignment for an object of aggregate type.
2023 This specifies the alignment for function pointers.
2024 The options for ``<type>`` are:
2026 * ``i``: The alignment of function pointers is independent of the alignment
2027 of functions, and is a multiple of ``<abi>``.
2028 * ``n``: The alignment of function pointers is a multiple of the explicit
2029 alignment specified on the function, and is a multiple of ``<abi>``.
2031 If present, specifies that llvm names are mangled in the output. Symbols
2032 prefixed with the mangling escape character ``\01`` are passed through
2033 directly to the assembler without the escape character. The mangling style
2036 * ``e``: ELF mangling: Private symbols get a ``.L`` prefix.
2037 * ``m``: Mips mangling: Private symbols get a ``$`` prefix.
2038 * ``o``: Mach-O mangling: Private symbols get ``L`` prefix. Other
2039 symbols get a ``_`` prefix.
2040 * ``x``: Windows x86 COFF mangling: Private symbols get the usual prefix.
2041 Regular C symbols get a ``_`` prefix. Functions with ``__stdcall``,
2042 ``__fastcall``, and ``__vectorcall`` have custom mangling that appends
2043 ``@N`` where N is the number of bytes used to pass parameters. C++ symbols
2044 starting with ``?`` are not mangled in any way.
2045 * ``w``: Windows COFF mangling: Similar to ``x``, except that normal C
2046 symbols do not receive a ``_`` prefix.
2047 ``n<size1>:<size2>:<size3>...``
2048 This specifies a set of native integer widths for the target CPU in
2049 bits. For example, it might contain ``n32`` for 32-bit PowerPC,
2050 ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of
2051 this set are considered to support most general arithmetic operations
2053 ``ni:<address space0>:<address space1>:<address space2>...``
2054 This specifies pointer types with the specified address spaces
2055 as :ref:`Non-Integral Pointer Type <nointptrtype>` s. The ``0``
2056 address space cannot be specified as non-integral.
2058 On every specification that takes a ``<abi>:<pref>``, specifying the
2059 ``<pref>`` alignment is optional. If omitted, the preceding ``:``
2060 should be omitted too and ``<pref>`` will be equal to ``<abi>``.
2062 When constructing the data layout for a given target, LLVM starts with a
2063 default set of specifications which are then (possibly) overridden by
2064 the specifications in the ``datalayout`` keyword. The default
2065 specifications are given in this list:
2067 - ``E`` - big endian
2068 - ``p:64:64:64`` - 64-bit pointers with 64-bit alignment.
2069 - ``p[n]:64:64:64`` - Other address spaces are assumed to be the
2070 same as the default address space.
2071 - ``S0`` - natural stack alignment is unspecified
2072 - ``i1:8:8`` - i1 is 8-bit (byte) aligned
2073 - ``i8:8:8`` - i8 is 8-bit (byte) aligned
2074 - ``i16:16:16`` - i16 is 16-bit aligned
2075 - ``i32:32:32`` - i32 is 32-bit aligned
2076 - ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
2077 alignment of 64-bits
2078 - ``f16:16:16`` - half is 16-bit aligned
2079 - ``f32:32:32`` - float is 32-bit aligned
2080 - ``f64:64:64`` - double is 64-bit aligned
2081 - ``f128:128:128`` - quad is 128-bit aligned
2082 - ``v64:64:64`` - 64-bit vector is 64-bit aligned
2083 - ``v128:128:128`` - 128-bit vector is 128-bit aligned
2084 - ``a:0:64`` - aggregates are 64-bit aligned
2086 When LLVM is determining the alignment for a given type, it uses the
2089 #. If the type sought is an exact match for one of the specifications,
2090 that specification is used.
2091 #. If no match is found, and the type sought is an integer type, then
2092 the smallest integer type that is larger than the bitwidth of the
2093 sought type is used. If none of the specifications are larger than
2094 the bitwidth then the largest integer type is used. For example,
2095 given the default specifications above, the i7 type will use the
2096 alignment of i8 (next largest) while both i65 and i256 will use the
2097 alignment of i64 (largest specified).
2098 #. If no match is found, and the type sought is a vector type, then the
2099 largest vector type that is smaller than the sought vector type will
2100 be used as a fall back. This happens because <128 x double> can be
2101 implemented in terms of 64 <2 x double>, for example.
2103 The function of the data layout string may not be what you expect.
2104 Notably, this is not a specification from the frontend of what alignment
2105 the code generator should use.
2107 Instead, if specified, the target data layout is required to match what
2108 the ultimate *code generator* expects. This string is used by the
2109 mid-level optimizers to improve code, and this only works if it matches
2110 what the ultimate code generator uses. There is no way to generate IR
2111 that does not embed this target-specific detail into the IR. If you
2112 don't specify the string, the default specifications will be used to
2113 generate a Data Layout and the optimization phases will operate
2114 accordingly and introduce target specificity into the IR with respect to
2115 these default specifications.
2122 A module may specify a target triple string that describes the target
2123 host. The syntax for the target triple is simply:
2125 .. code-block:: llvm
2127 target triple = "x86_64-apple-macosx10.7.0"
2129 The *target triple* string consists of a series of identifiers delimited
2130 by the minus sign character ('-'). The canonical forms are:
2134 ARCHITECTURE-VENDOR-OPERATING_SYSTEM
2135 ARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT
2137 This information is passed along to the backend so that it generates
2138 code for the proper architecture. It's possible to override this on the
2139 command line with the ``-mtriple`` command line option.
2141 .. _pointeraliasing:
2143 Pointer Aliasing Rules
2144 ----------------------
2146 Any memory access must be done through a pointer value associated with
2147 an address range of the memory access, otherwise the behavior is
2148 undefined. Pointer values are associated with address ranges according
2149 to the following rules:
2151 - A pointer value is associated with the addresses associated with any
2152 value it is *based* on.
2153 - An address of a global variable is associated with the address range
2154 of the variable's storage.
2155 - The result value of an allocation instruction is associated with the
2156 address range of the allocated storage.
2157 - A null pointer in the default address-space is associated with no
2159 - An :ref:`undef value <undefvalues>` in *any* address-space is
2160 associated with no address.
2161 - An integer constant other than zero or a pointer value returned from
2162 a function not defined within LLVM may be associated with address
2163 ranges allocated through mechanisms other than those provided by
2164 LLVM. Such ranges shall not overlap with any ranges of addresses
2165 allocated by mechanisms provided by LLVM.
2167 A pointer value is *based* on another pointer value according to the
2170 - A pointer value formed from a scalar ``getelementptr`` operation is *based* on
2171 the pointer-typed operand of the ``getelementptr``.
2172 - The pointer in lane *l* of the result of a vector ``getelementptr`` operation
2173 is *based* on the pointer in lane *l* of the vector-of-pointers-typed operand
2174 of the ``getelementptr``.
2175 - The result value of a ``bitcast`` is *based* on the operand of the
2177 - A pointer value formed by an ``inttoptr`` is *based* on all pointer
2178 values that contribute (directly or indirectly) to the computation of
2179 the pointer's value.
2180 - The "*based* on" relationship is transitive.
2182 Note that this definition of *"based"* is intentionally similar to the
2183 definition of *"based"* in C99, though it is slightly weaker.
2185 LLVM IR does not associate types with memory. The result type of a
2186 ``load`` merely indicates the size and alignment of the memory from
2187 which to load, as well as the interpretation of the value. The first
2188 operand type of a ``store`` similarly only indicates the size and
2189 alignment of the store.
2191 Consequently, type-based alias analysis, aka TBAA, aka
2192 ``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR.
2193 :ref:`Metadata <metadata>` may be used to encode additional information
2194 which specialized optimization passes may use to implement type-based
2199 Volatile Memory Accesses
2200 ------------------------
2202 Certain memory accesses, such as :ref:`load <i_load>`'s,
2203 :ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be
2204 marked ``volatile``. The optimizers must not change the number of
2205 volatile operations or change their order of execution relative to other
2206 volatile operations. The optimizers *may* change the order of volatile
2207 operations relative to non-volatile operations. This is not Java's
2208 "volatile" and has no cross-thread synchronization behavior.
2210 A volatile load or store may have additional target-specific semantics.
2211 Any volatile operation can have side effects, and any volatile operation
2212 can read and/or modify state which is not accessible via a regular load
2213 or store in this module. Volatile operations may use addresses which do
2214 not point to memory (like MMIO registers). This means the compiler may
2215 not use a volatile operation to prove a non-volatile access to that
2216 address has defined behavior.
2218 The allowed side-effects for volatile accesses are limited. If a
2219 non-volatile store to a given address would be legal, a volatile
2220 operation may modify the memory at that address. A volatile operation
2221 may not modify any other memory accessible by the module being compiled.
2222 A volatile operation may not call any code in the current module.
2224 The compiler may assume execution will continue after a volatile operation,
2225 so operations which modify memory or may have undefined behavior can be
2226 hoisted past a volatile operation.
2228 IR-level volatile loads and stores cannot safely be optimized into
2229 llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are
2230 flagged volatile. Likewise, the backend should never split or merge
2231 target-legal volatile load/store instructions.
2233 .. admonition:: Rationale
2235 Platforms may rely on volatile loads and stores of natively supported
2236 data width to be executed as single instruction. For example, in C
2237 this holds for an l-value of volatile primitive type with native
2238 hardware support, but not necessarily for aggregate types. The
2239 frontend upholds these expectations, which are intentionally
2240 unspecified in the IR. The rules above ensure that IR transformations
2241 do not violate the frontend's contract with the language.
2245 Memory Model for Concurrent Operations
2246 --------------------------------------
2248 The LLVM IR does not define any way to start parallel threads of
2249 execution or to register signal handlers. Nonetheless, there are
2250 platform-specific ways to create them, and we define LLVM IR's behavior
2251 in their presence. This model is inspired by the C++0x memory model.
2253 For a more informal introduction to this model, see the :doc:`Atomics`.
2255 We define a *happens-before* partial order as the least partial order
2258 - Is a superset of single-thread program order, and
2259 - When a *synchronizes-with* ``b``, includes an edge from ``a`` to
2260 ``b``. *Synchronizes-with* pairs are introduced by platform-specific
2261 techniques, like pthread locks, thread creation, thread joining,
2262 etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering
2263 Constraints <ordering>`).
2265 Note that program order does not introduce *happens-before* edges
2266 between a thread and signals executing inside that thread.
2268 Every (defined) read operation (load instructions, memcpy, atomic
2269 loads/read-modify-writes, etc.) R reads a series of bytes written by
2270 (defined) write operations (store instructions, atomic
2271 stores/read-modify-writes, memcpy, etc.). For the purposes of this
2272 section, initialized globals are considered to have a write of the
2273 initializer which is atomic and happens before any other read or write
2274 of the memory in question. For each byte of a read R, R\ :sub:`byte`
2275 may see any write to the same byte, except:
2277 - If write\ :sub:`1` happens before write\ :sub:`2`, and
2278 write\ :sub:`2` happens before R\ :sub:`byte`, then
2279 R\ :sub:`byte` does not see write\ :sub:`1`.
2280 - If R\ :sub:`byte` happens before write\ :sub:`3`, then
2281 R\ :sub:`byte` does not see write\ :sub:`3`.
2283 Given that definition, R\ :sub:`byte` is defined as follows:
2285 - If R is volatile, the result is target-dependent. (Volatile is
2286 supposed to give guarantees which can support ``sig_atomic_t`` in
2287 C/C++, and may be used for accesses to addresses that do not behave
2288 like normal memory. It does not generally provide cross-thread
2290 - Otherwise, if there is no write to the same byte that happens before
2291 R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte.
2292 - Otherwise, if R\ :sub:`byte` may see exactly one write,
2293 R\ :sub:`byte` returns the value written by that write.
2294 - Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may
2295 see are atomic, it chooses one of the values written. See the :ref:`Atomic
2296 Memory Ordering Constraints <ordering>` section for additional
2297 constraints on how the choice is made.
2298 - Otherwise R\ :sub:`byte` returns ``undef``.
2300 R returns the value composed of the series of bytes it read. This
2301 implies that some bytes within the value may be ``undef`` **without**
2302 the entire value being ``undef``. Note that this only defines the
2303 semantics of the operation; it doesn't mean that targets will emit more
2304 than one instruction to read the series of bytes.
2306 Note that in cases where none of the atomic intrinsics are used, this
2307 model places only one restriction on IR transformations on top of what
2308 is required for single-threaded execution: introducing a store to a byte
2309 which might not otherwise be stored is not allowed in general.
2310 (Specifically, in the case where another thread might write to and read
2311 from an address, introducing a store can change a load that may see
2312 exactly one write into a load that may see multiple writes.)
2316 Atomic Memory Ordering Constraints
2317 ----------------------------------
2319 Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`,
2320 :ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`,
2321 :ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take
2322 ordering parameters that determine which other atomic instructions on
2323 the same address they *synchronize with*. These semantics are borrowed
2324 from Java and C++0x, but are somewhat more colloquial. If these
2325 descriptions aren't precise enough, check those specs (see spec
2326 references in the :doc:`atomics guide <Atomics>`).
2327 :ref:`fence <i_fence>` instructions treat these orderings somewhat
2328 differently since they don't take an address. See that instruction's
2329 documentation for details.
2331 For a simpler introduction to the ordering constraints, see the
2335 The set of values that can be read is governed by the happens-before
2336 partial order. A value cannot be read unless some operation wrote
2337 it. This is intended to provide a guarantee strong enough to model
2338 Java's non-volatile shared variables. This ordering cannot be
2339 specified for read-modify-write operations; it is not strong enough
2340 to make them atomic in any interesting way.
2342 In addition to the guarantees of ``unordered``, there is a single
2343 total order for modifications by ``monotonic`` operations on each
2344 address. All modification orders must be compatible with the
2345 happens-before order. There is no guarantee that the modification
2346 orders can be combined to a global total order for the whole program
2347 (and this often will not be possible). The read in an atomic
2348 read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and
2349 :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification
2350 order immediately before the value it writes. If one atomic read
2351 happens before another atomic read of the same address, the later
2352 read must see the same value or a later value in the address's
2353 modification order. This disallows reordering of ``monotonic`` (or
2354 stronger) operations on the same address. If an address is written
2355 ``monotonic``-ally by one thread, and other threads ``monotonic``-ally
2356 read that address repeatedly, the other threads must eventually see
2357 the write. This corresponds to the C++0x/C1x
2358 ``memory_order_relaxed``.
2360 In addition to the guarantees of ``monotonic``, a
2361 *synchronizes-with* edge may be formed with a ``release`` operation.
2362 This is intended to model C++'s ``memory_order_acquire``.
2364 In addition to the guarantees of ``monotonic``, if this operation
2365 writes a value which is subsequently read by an ``acquire``
2366 operation, it *synchronizes-with* that operation. (This isn't a
2367 complete description; see the C++0x definition of a release
2368 sequence.) This corresponds to the C++0x/C1x
2369 ``memory_order_release``.
2370 ``acq_rel`` (acquire+release)
2371 Acts as both an ``acquire`` and ``release`` operation on its
2372 address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``.
2373 ``seq_cst`` (sequentially consistent)
2374 In addition to the guarantees of ``acq_rel`` (``acquire`` for an
2375 operation that only reads, ``release`` for an operation that only
2376 writes), there is a global total order on all
2377 sequentially-consistent operations on all addresses, which is
2378 consistent with the *happens-before* partial order and with the
2379 modification orders of all the affected addresses. Each
2380 sequentially-consistent read sees the last preceding write to the
2381 same address in this global order. This corresponds to the C++0x/C1x
2382 ``memory_order_seq_cst`` and Java volatile.
2386 If an atomic operation is marked ``syncscope("singlethread")``, it only
2387 *synchronizes with* and only participates in the seq\_cst total orderings of
2388 other operations running in the same thread (for example, in signal handlers).
2390 If an atomic operation is marked ``syncscope("<target-scope>")``, where
2391 ``<target-scope>`` is a target specific synchronization scope, then it is target
2392 dependent if it *synchronizes with* and participates in the seq\_cst total
2393 orderings of other operations.
2395 Otherwise, an atomic operation that is not marked ``syncscope("singlethread")``
2396 or ``syncscope("<target-scope>")`` *synchronizes with* and participates in the
2397 seq\_cst total orderings of other operations that are not marked
2398 ``syncscope("singlethread")`` or ``syncscope("<target-scope>")``.
2402 Floating-Point Environment
2403 --------------------------
2405 The default LLVM floating-point environment assumes that floating-point
2406 instructions do not have side effects. Results assume the round-to-nearest
2407 rounding mode. No floating-point exception state is maintained in this
2408 environment. Therefore, there is no attempt to create or preserve invalid
2409 operation (SNaN) or division-by-zero exceptions.
2411 The benefit of this exception-free assumption is that floating-point
2412 operations may be speculated freely without any other fast-math relaxations
2413 to the floating-point model.
2415 Code that requires different behavior than this should use the
2416 :ref:`Constrained Floating-Point Intrinsics <constrainedfp>`.
2423 LLVM IR floating-point operations (:ref:`fadd <i_fadd>`,
2424 :ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
2425 :ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`) and :ref:`call <i_call>`
2426 may use the following flags to enable otherwise unsafe
2427 floating-point transformations.
2430 No NaNs - Allow optimizations to assume the arguments and result are not
2431 NaN. If an argument is a nan, or the result would be a nan, it produces
2432 a :ref:`poison value <poisonvalues>` instead.
2435 No Infs - Allow optimizations to assume the arguments and result are not
2436 +/-Inf. If an argument is +/-Inf, or the result would be +/-Inf, it
2437 produces a :ref:`poison value <poisonvalues>` instead.
2440 No Signed Zeros - Allow optimizations to treat the sign of a zero
2441 argument or result as insignificant.
2444 Allow Reciprocal - Allow optimizations to use the reciprocal of an
2445 argument rather than perform division.
2448 Allow floating-point contraction (e.g. fusing a multiply followed by an
2449 addition into a fused multiply-and-add).
2452 Approximate functions - Allow substitution of approximate calculations for
2453 functions (sin, log, sqrt, etc). See floating-point intrinsic definitions
2454 for places where this can apply to LLVM's intrinsic math functions.
2457 Allow reassociation transformations for floating-point instructions.
2458 This may dramatically change results in floating-point.
2461 This flag implies all of the others.
2465 Use-list Order Directives
2466 -------------------------
2468 Use-list directives encode the in-memory order of each use-list, allowing the
2469 order to be recreated. ``<order-indexes>`` is a comma-separated list of
2470 indexes that are assigned to the referenced value's uses. The referenced
2471 value's use-list is immediately sorted by these indexes.
2473 Use-list directives may appear at function scope or global scope. They are not
2474 instructions, and have no effect on the semantics of the IR. When they're at
2475 function scope, they must appear after the terminator of the final basic block.
2477 If basic blocks have their address taken via ``blockaddress()`` expressions,
2478 ``uselistorder_bb`` can be used to reorder their use-lists from outside their
2485 uselistorder <ty> <value>, { <order-indexes> }
2486 uselistorder_bb @function, %block { <order-indexes> }
2492 define void @foo(i32 %arg1, i32 %arg2) {
2494 ; ... instructions ...
2496 ; ... instructions ...
2498 ; At function scope.
2499 uselistorder i32 %arg1, { 1, 0, 2 }
2500 uselistorder label %bb, { 1, 0 }
2504 uselistorder i32* @global, { 1, 2, 0 }
2505 uselistorder i32 7, { 1, 0 }
2506 uselistorder i32 (i32) @bar, { 1, 0 }
2507 uselistorder_bb @foo, %bb, { 5, 1, 3, 2, 0, 4 }
2509 .. _source_filename:
2514 The *source filename* string is set to the original module identifier,
2515 which will be the name of the compiled source file when compiling from
2516 source through the clang front end, for example. It is then preserved through
2519 This is currently necessary to generate a consistent unique global
2520 identifier for local functions used in profile data, which prepends the
2521 source file name to the local function name.
2523 The syntax for the source file name is simply:
2525 .. code-block:: text
2527 source_filename = "/path/to/source.c"
2534 The LLVM type system is one of the most important features of the
2535 intermediate representation. Being typed enables a number of
2536 optimizations to be performed on the intermediate representation
2537 directly, without having to do extra analyses on the side before the
2538 transformation. A strong type system makes it easier to read the
2539 generated code and enables novel analyses and transformations that are
2540 not feasible to perform on normal three address code representations.
2550 The void type does not represent any value and has no size.
2568 The function type can be thought of as a function signature. It consists of a
2569 return type and a list of formal parameter types. The return type of a function
2570 type is a void type or first class type --- except for :ref:`label <t_label>`
2571 and :ref:`metadata <t_metadata>` types.
2577 <returntype> (<parameter list>)
2579 ...where '``<parameter list>``' is a comma-separated list of type
2580 specifiers. Optionally, the parameter list may include a type ``...``, which
2581 indicates that the function takes a variable number of arguments. Variable
2582 argument functions can access their arguments with the :ref:`variable argument
2583 handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type
2584 except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`.
2588 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2589 | ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` |
2590 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2591 | ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
2592 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2593 | ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. |
2594 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2595 | ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values |
2596 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2603 The :ref:`first class <t_firstclass>` types are perhaps the most important.
2604 Values of these types are the only ones which can be produced by
2612 These are the types that are valid in registers from CodeGen's perspective.
2621 The integer type is a very simple type that simply specifies an
2622 arbitrary bit width for the integer type desired. Any bit width from 1
2623 bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified.
2631 The number of bits the integer will occupy is specified by the ``N``
2637 +----------------+------------------------------------------------+
2638 | ``i1`` | a single-bit integer. |
2639 +----------------+------------------------------------------------+
2640 | ``i32`` | a 32-bit integer. |
2641 +----------------+------------------------------------------------+
2642 | ``i1942652`` | a really big integer of over 1 million bits. |
2643 +----------------+------------------------------------------------+
2647 Floating-Point Types
2648 """"""""""""""""""""
2657 - 16-bit floating-point value
2660 - 32-bit floating-point value
2663 - 64-bit floating-point value
2666 - 128-bit floating-point value (112-bit mantissa)
2669 - 80-bit floating-point value (X87)
2672 - 128-bit floating-point value (two 64-bits)
2674 The binary format of half, float, double, and fp128 correspond to the
2675 IEEE-754-2008 specifications for binary16, binary32, binary64, and binary128
2683 The x86_mmx type represents a value held in an MMX register on an x86
2684 machine. The operations allowed on it are quite limited: parameters and
2685 return values, load and store, and bitcast. User-specified MMX
2686 instructions are represented as intrinsic or asm calls with arguments
2687 and/or results of this type. There are no arrays, vectors or constants
2704 The pointer type is used to specify memory locations. Pointers are
2705 commonly used to reference objects in memory.
2707 Pointer types may have an optional address space attribute defining the
2708 numbered address space where the pointed-to object resides. The default
2709 address space is number zero. The semantics of non-zero address spaces
2710 are target-specific.
2712 Note that LLVM does not permit pointers to void (``void*``) nor does it
2713 permit pointers to labels (``label*``). Use ``i8*`` instead.
2723 +-------------------------+--------------------------------------------------------------------------------------------------------------+
2724 | ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. |
2725 +-------------------------+--------------------------------------------------------------------------------------------------------------+
2726 | ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. |
2727 +-------------------------+--------------------------------------------------------------------------------------------------------------+
2728 | ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. |
2729 +-------------------------+--------------------------------------------------------------------------------------------------------------+
2738 A vector type is a simple derived type that represents a vector of
2739 elements. Vector types are used when multiple primitive data are
2740 operated in parallel using a single instruction (SIMD). A vector type
2741 requires a size (number of elements), an underlying primitive data type,
2742 and a scalable property to represent vectors where the exact hardware
2743 vector length is unknown at compile time. Vector types are considered
2744 :ref:`first class <t_firstclass>`.
2750 < <# elements> x <elementtype> > ; Fixed-length vector
2751 < vscale x <# elements> x <elementtype> > ; Scalable vector
2753 The number of elements is a constant integer value larger than 0;
2754 elementtype may be any integer, floating-point or pointer type. Vectors
2755 of size zero are not allowed. For scalable vectors, the total number of
2756 elements is a constant multiple (called vscale) of the specified number
2757 of elements; vscale is a positive integer that is unknown at compile time
2758 and the same hardware-dependent constant for all scalable vectors at run
2759 time. The size of a specific scalable vector type is thus constant within
2760 IR, even if the exact size in bytes cannot be determined until run time.
2764 +------------------------+----------------------------------------------------+
2765 | ``<4 x i32>`` | Vector of 4 32-bit integer values. |
2766 +------------------------+----------------------------------------------------+
2767 | ``<8 x float>`` | Vector of 8 32-bit floating-point values. |
2768 +------------------------+----------------------------------------------------+
2769 | ``<2 x i64>`` | Vector of 2 64-bit integer values. |
2770 +------------------------+----------------------------------------------------+
2771 | ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. |
2772 +------------------------+----------------------------------------------------+
2773 | ``<vscale x 4 x i32>`` | Vector with a multiple of 4 32-bit integer values. |
2774 +------------------------+----------------------------------------------------+
2783 The label type represents code labels.
2798 The token type is used when a value is associated with an instruction
2799 but all uses of the value must not attempt to introspect or obscure it.
2800 As such, it is not appropriate to have a :ref:`phi <i_phi>` or
2801 :ref:`select <i_select>` of type token.
2818 The metadata type represents embedded metadata. No derived types may be
2819 created from metadata except for :ref:`function <t_function>` arguments.
2832 Aggregate Types are a subset of derived types that can contain multiple
2833 member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are
2834 aggregate types. :ref:`Vectors <t_vector>` are not considered to be
2844 The array type is a very simple derived type that arranges elements
2845 sequentially in memory. The array type requires a size (number of
2846 elements) and an underlying data type.
2852 [<# elements> x <elementtype>]
2854 The number of elements is a constant integer value; ``elementtype`` may
2855 be any type with a size.
2859 +------------------+--------------------------------------+
2860 | ``[40 x i32]`` | Array of 40 32-bit integer values. |
2861 +------------------+--------------------------------------+
2862 | ``[41 x i32]`` | Array of 41 32-bit integer values. |
2863 +------------------+--------------------------------------+
2864 | ``[4 x i8]`` | Array of 4 8-bit integer values. |
2865 +------------------+--------------------------------------+
2867 Here are some examples of multidimensional arrays:
2869 +-----------------------------+----------------------------------------------------------+
2870 | ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. |
2871 +-----------------------------+----------------------------------------------------------+
2872 | ``[12 x [10 x float]]`` | 12x10 array of single precision floating-point values. |
2873 +-----------------------------+----------------------------------------------------------+
2874 | ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. |
2875 +-----------------------------+----------------------------------------------------------+
2877 There is no restriction on indexing beyond the end of the array implied
2878 by a static type (though there are restrictions on indexing beyond the
2879 bounds of an allocated object in some cases). This means that
2880 single-dimension 'variable sized array' addressing can be implemented in
2881 LLVM with a zero length array type. An implementation of 'pascal style
2882 arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for
2892 The structure type is used to represent a collection of data members
2893 together in memory. The elements of a structure may be any type that has
2896 Structures in memory are accessed using '``load``' and '``store``' by
2897 getting a pointer to a field with the '``getelementptr``' instruction.
2898 Structures in registers are accessed using the '``extractvalue``' and
2899 '``insertvalue``' instructions.
2901 Structures may optionally be "packed" structures, which indicate that
2902 the alignment of the struct is one byte, and that there is no padding
2903 between the elements. In non-packed structs, padding between field types
2904 is inserted as defined by the DataLayout string in the module, which is
2905 required to match what the underlying code generator expects.
2907 Structures can either be "literal" or "identified". A literal structure
2908 is defined inline with other types (e.g. ``{i32, i32}*``) whereas
2909 identified types are always defined at the top level with a name.
2910 Literal types are uniqued by their contents and can never be recursive
2911 or opaque since there is no way to write one. Identified types can be
2912 recursive, can be opaqued, and are never uniqued.
2918 %T1 = type { <type list> } ; Identified normal struct type
2919 %T2 = type <{ <type list> }> ; Identified packed struct type
2923 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2924 | ``{ i32, i32, i32 }`` | A triple of three ``i32`` values |
2925 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2926 | ``{ float, i32 (i32) * }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32``, returning an ``i32``. |
2927 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2928 | ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. |
2929 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2933 Opaque Structure Types
2934 """"""""""""""""""""""
2938 Opaque structure types are used to represent named structure types that
2939 do not have a body specified. This corresponds (for example) to the C
2940 notion of a forward declared structure.
2951 +--------------+-------------------+
2952 | ``opaque`` | An opaque type. |
2953 +--------------+-------------------+
2960 LLVM has several different basic types of constants. This section
2961 describes them all and their syntax.
2966 **Boolean constants**
2967 The two strings '``true``' and '``false``' are both valid constants
2969 **Integer constants**
2970 Standard integers (such as '4') are constants of the
2971 :ref:`integer <t_integer>` type. Negative numbers may be used with
2973 **Floating-point constants**
2974 Floating-point constants use standard decimal notation (e.g.
2975 123.421), exponential notation (e.g. 1.23421e+2), or a more precise
2976 hexadecimal notation (see below). The assembler requires the exact
2977 decimal value of a floating-point constant. For example, the
2978 assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating
2979 decimal in binary. Floating-point constants must have a
2980 :ref:`floating-point <t_floating>` type.
2981 **Null pointer constants**
2982 The identifier '``null``' is recognized as a null pointer constant
2983 and must be of :ref:`pointer type <t_pointer>`.
2985 The identifier '``none``' is recognized as an empty token constant
2986 and must be of :ref:`token type <t_token>`.
2988 The one non-intuitive notation for constants is the hexadecimal form of
2989 floating-point constants. For example, the form
2990 '``double 0x432ff973cafa8000``' is equivalent to (but harder to read
2991 than) '``double 4.5e+15``'. The only time hexadecimal floating-point
2992 constants are required (and the only time that they are generated by the
2993 disassembler) is when a floating-point constant must be emitted but it
2994 cannot be represented as a decimal floating-point number in a reasonable
2995 number of digits. For example, NaN's, infinities, and other special
2996 values are represented in their IEEE hexadecimal format so that assembly
2997 and disassembly do not cause any bits to change in the constants.
2999 When using the hexadecimal form, constants of types half, float, and
3000 double are represented using the 16-digit form shown above (which
3001 matches the IEEE754 representation for double); half and float values
3002 must, however, be exactly representable as IEEE 754 half and single
3003 precision, respectively. Hexadecimal format is always used for long
3004 double, and there are three forms of long double. The 80-bit format used
3005 by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The
3006 128-bit format used by PowerPC (two adjacent doubles) is represented by
3007 ``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is
3008 represented by ``0xL`` followed by 32 hexadecimal digits. Long doubles
3009 will only work if they match the long double format on your target.
3010 The IEEE 16-bit format (half precision) is represented by ``0xH``
3011 followed by 4 hexadecimal digits. All hexadecimal formats are big-endian
3012 (sign bit at the left).
3014 There are no constants of type x86_mmx.
3016 .. _complexconstants:
3021 Complex constants are a (potentially recursive) combination of simple
3022 constants and smaller complex constants.
3024 **Structure constants**
3025 Structure constants are represented with notation similar to
3026 structure type definitions (a comma separated list of elements,
3027 surrounded by braces (``{}``)). For example:
3028 "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as
3029 "``@G = external global i32``". Structure constants must have
3030 :ref:`structure type <t_struct>`, and the number and types of elements
3031 must match those specified by the type.
3033 Array constants are represented with notation similar to array type
3034 definitions (a comma separated list of elements, surrounded by
3035 square brackets (``[]``)). For example:
3036 "``[ i32 42, i32 11, i32 74 ]``". Array constants must have
3037 :ref:`array type <t_array>`, and the number and types of elements must
3038 match those specified by the type. As a special case, character array
3039 constants may also be represented as a double-quoted string using the ``c``
3040 prefix. For example: "``c"Hello World\0A\00"``".
3041 **Vector constants**
3042 Vector constants are represented with notation similar to vector
3043 type definitions (a comma separated list of elements, surrounded by
3044 less-than/greater-than's (``<>``)). For example:
3045 "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants
3046 must have :ref:`vector type <t_vector>`, and the number and types of
3047 elements must match those specified by the type.
3048 **Zero initialization**
3049 The string '``zeroinitializer``' can be used to zero initialize a
3050 value to zero of *any* type, including scalar and
3051 :ref:`aggregate <t_aggregate>` types. This is often used to avoid
3052 having to print large zero initializers (e.g. for large arrays) and
3053 is always exactly equivalent to using explicit zero initializers.
3055 A metadata node is a constant tuple without types. For example:
3056 "``!{!0, !{!2, !0}, !"test"}``". Metadata can reference constant values,
3057 for example: "``!{!0, i32 0, i8* @global, i64 (i64)* @function, !"str"}``".
3058 Unlike other typed constants that are meant to be interpreted as part of
3059 the instruction stream, metadata is a place to attach additional
3060 information such as debug info.
3062 Global Variable and Function Addresses
3063 --------------------------------------
3065 The addresses of :ref:`global variables <globalvars>` and
3066 :ref:`functions <functionstructure>` are always implicitly valid
3067 (link-time) constants. These constants are explicitly referenced when
3068 the :ref:`identifier for the global <identifiers>` is used and always have
3069 :ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM
3072 .. code-block:: llvm
3076 @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
3083 The string '``undef``' can be used anywhere a constant is expected, and
3084 indicates that the user of the value may receive an unspecified
3085 bit-pattern. Undefined values may be of any type (other than '``label``'
3086 or '``void``') and be used anywhere a constant is permitted.
3088 Undefined values are useful because they indicate to the compiler that
3089 the program is well defined no matter what value is used. This gives the
3090 compiler more freedom to optimize. Here are some examples of
3091 (potentially surprising) transformations that are valid (in pseudo IR):
3093 .. code-block:: llvm
3103 This is safe because all of the output bits are affected by the undef
3104 bits. Any output bit can have a zero or one depending on the input bits.
3106 .. code-block:: llvm
3114 %A = %X ;; By choosing undef as 0
3115 %B = %X ;; By choosing undef as -1
3120 These logical operations have bits that are not always affected by the
3121 input. For example, if ``%X`` has a zero bit, then the output of the
3122 '``and``' operation will always be a zero for that bit, no matter what
3123 the corresponding bit from the '``undef``' is. As such, it is unsafe to
3124 optimize or assume that the result of the '``and``' is '``undef``'.
3125 However, it is safe to assume that all bits of the '``undef``' could be
3126 0, and optimize the '``and``' to 0. Likewise, it is safe to assume that
3127 all the bits of the '``undef``' operand to the '``or``' could be set,
3128 allowing the '``or``' to be folded to -1.
3130 .. code-block:: llvm
3132 %A = select undef, %X, %Y
3133 %B = select undef, 42, %Y
3134 %C = select %X, %Y, undef
3144 This set of examples shows that undefined '``select``' (and conditional
3145 branch) conditions can go *either way*, but they have to come from one
3146 of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were
3147 both known to have a clear low bit, then ``%A`` would have to have a
3148 cleared low bit. However, in the ``%C`` example, the optimizer is
3149 allowed to assume that the '``undef``' operand could be the same as
3150 ``%Y``, allowing the whole '``select``' to be eliminated.
3152 .. code-block:: text
3154 %A = xor undef, undef
3171 This example points out that two '``undef``' operands are not
3172 necessarily the same. This can be surprising to people (and also matches
3173 C semantics) where they assume that "``X^X``" is always zero, even if
3174 ``X`` is undefined. This isn't true for a number of reasons, but the
3175 short answer is that an '``undef``' "variable" can arbitrarily change
3176 its value over its "live range". This is true because the variable
3177 doesn't actually *have a live range*. Instead, the value is logically
3178 read from arbitrary registers that happen to be around when needed, so
3179 the value is not necessarily consistent over time. In fact, ``%A`` and
3180 ``%C`` need to have the same semantics or the core LLVM "replace all
3181 uses with" concept would not hold.
3183 .. code-block:: llvm
3191 These examples show the crucial difference between an *undefined value*
3192 and *undefined behavior*. An undefined value (like '``undef``') is
3193 allowed to have an arbitrary bit-pattern. This means that the ``%A``
3194 operation can be constant folded to '``0``', because the '``undef``'
3195 could be zero, and zero divided by any value is zero.
3196 However, in the second example, we can make a more aggressive
3197 assumption: because the ``undef`` is allowed to be an arbitrary value,
3198 we are allowed to assume that it could be zero. Since a divide by zero
3199 has *undefined behavior*, we are allowed to assume that the operation
3200 does not execute at all. This allows us to delete the divide and all
3201 code after it. Because the undefined operation "can't happen", the
3202 optimizer can assume that it occurs in dead code.
3204 .. code-block:: text
3206 a: store undef -> %X
3207 b: store %X -> undef
3212 A store *of* an undefined value can be assumed to not have any effect;
3213 we can assume that the value is overwritten with bits that happen to
3214 match what was already there. However, a store *to* an undefined
3215 location could clobber arbitrary memory, therefore, it has undefined
3223 In order to facilitate speculative execution, many instructions do not
3224 invoke immediate undefined behavior when provided with illegal operands,
3225 and return a poison value instead.
3227 There is currently no way of representing a poison value in the IR; they
3228 only exist when produced by operations such as :ref:`add <i_add>` with
3231 Poison value behavior is defined in terms of value *dependence*:
3233 - Values other than :ref:`phi <i_phi>` nodes depend on their operands.
3234 - :ref:`Phi <i_phi>` nodes depend on the operand corresponding to
3235 their dynamic predecessor basic block.
3236 - Function arguments depend on the corresponding actual argument values
3237 in the dynamic callers of their functions.
3238 - :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>`
3239 instructions that dynamically transfer control back to them.
3240 - :ref:`Invoke <i_invoke>` instructions depend on the
3241 :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing
3242 call instructions that dynamically transfer control back to them.
3243 - Non-volatile loads and stores depend on the most recent stores to all
3244 of the referenced memory addresses, following the order in the IR
3245 (including loads and stores implied by intrinsics such as
3246 :ref:`@llvm.memcpy <int_memcpy>`.)
3247 - An instruction with externally visible side effects depends on the
3248 most recent preceding instruction with externally visible side
3249 effects, following the order in the IR. (This includes :ref:`volatile
3250 operations <volatile>`.)
3251 - An instruction *control-depends* on a :ref:`terminator
3252 instruction <terminators>` if the terminator instruction has
3253 multiple successors and the instruction is always executed when
3254 control transfers to one of the successors, and may not be executed
3255 when control is transferred to another.
3256 - Additionally, an instruction also *control-depends* on a terminator
3257 instruction if the set of instructions it otherwise depends on would
3258 be different if the terminator had transferred control to a different
3260 - Dependence is transitive.
3262 An instruction that *depends* on a poison value, produces a poison value
3263 itself. A poison value may be relaxed into an
3264 :ref:`undef value <undefvalues>`, which takes an arbitrary bit-pattern.
3266 This means that immediate undefined behavior occurs if a poison value is
3267 used as an instruction operand that has any values that trigger undefined
3268 behavior. Notably this includes (but is not limited to):
3270 - The pointer operand of a :ref:`load <i_load>`, :ref:`store <i_store>` or
3271 any other pointer dereferencing instruction (independent of address
3273 - The divisor operand of a ``udiv``, ``sdiv``, ``urem`` or ``srem``
3276 Additionally, undefined behavior occurs if a side effect *depends* on poison.
3277 This includes side effects that are control dependent on a poisoned branch.
3279 Here are some examples:
3281 .. code-block:: llvm
3284 %poison = sub nuw i32 0, 1 ; Results in a poison value.
3285 %still_poison = and i32 %poison, 0 ; 0, but also poison.
3286 %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison
3287 store i32 0, i32* %poison_yet_again ; Undefined behavior due to
3290 store i32 %poison, i32* @g ; Poison value stored to memory.
3291 %poison2 = load i32, i32* @g ; Poison value loaded back from memory.
3293 %narrowaddr = bitcast i32* @g to i16*
3294 %wideaddr = bitcast i32* @g to i64*
3295 %poison3 = load i16, i16* %narrowaddr ; Returns a poison value.
3296 %poison4 = load i64, i64* %wideaddr ; Returns a poison value.
3298 %cmp = icmp slt i32 %poison, 0 ; Returns a poison value.
3299 br i1 %cmp, label %true, label %end ; Branch to either destination.
3302 store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so
3303 ; it has undefined behavior.
3307 %p = phi i32 [ 0, %entry ], [ 1, %true ]
3308 ; Both edges into this PHI are
3309 ; control-dependent on %cmp, so this
3310 ; always results in a poison value.
3312 store volatile i32 0, i32* @g ; This would depend on the store in %true
3313 ; if %cmp is true, or the store in %entry
3314 ; otherwise, so this is undefined behavior.
3316 br i1 %cmp, label %second_true, label %second_end
3317 ; The same branch again, but this time the
3318 ; true block doesn't have side effects.
3325 store volatile i32 0, i32* @g ; This time, the instruction always depends
3326 ; on the store in %end. Also, it is
3327 ; control-equivalent to %end, so this is
3328 ; well-defined (ignoring earlier undefined
3329 ; behavior in this example).
3333 Addresses of Basic Blocks
3334 -------------------------
3336 ``blockaddress(@function, %block)``
3338 The '``blockaddress``' constant computes the address of the specified
3339 basic block in the specified function, and always has an ``i8*`` type.
3340 Taking the address of the entry block is illegal.
3342 This value only has defined behavior when used as an operand to the
3343 ':ref:`indirectbr <i_indirectbr>`' or ':ref:`callbr <i_callbr>`'instruction, or
3344 for comparisons against null. Pointer equality tests between labels addresses
3345 results in undefined behavior --- though, again, comparison against null is ok,
3346 and no label is equal to the null pointer. This may be passed around as an
3347 opaque pointer sized value as long as the bits are not inspected. This
3348 allows ``ptrtoint`` and arithmetic to be performed on these values so
3349 long as the original value is reconstituted before the ``indirectbr`` or
3350 ``callbr`` instruction.
3352 Finally, some targets may provide defined semantics when using the value
3353 as the operand to an inline assembly, but that is target specific.
3357 Constant Expressions
3358 --------------------
3360 Constant expressions are used to allow expressions involving other
3361 constants to be used as constants. Constant expressions may be of any
3362 :ref:`first class <t_firstclass>` type and may involve any LLVM operation
3363 that does not have side effects (e.g. load and call are not supported).
3364 The following is the syntax for constant expressions:
3366 ``trunc (CST to TYPE)``
3367 Perform the :ref:`trunc operation <i_trunc>` on constants.
3368 ``zext (CST to TYPE)``
3369 Perform the :ref:`zext operation <i_zext>` on constants.
3370 ``sext (CST to TYPE)``
3371 Perform the :ref:`sext operation <i_sext>` on constants.
3372 ``fptrunc (CST to TYPE)``
3373 Truncate a floating-point constant to another floating-point type.
3374 The size of CST must be larger than the size of TYPE. Both types
3375 must be floating-point.
3376 ``fpext (CST to TYPE)``
3377 Floating-point extend a constant to another type. The size of CST
3378 must be smaller or equal to the size of TYPE. Both types must be
3380 ``fptoui (CST to TYPE)``
3381 Convert a floating-point constant to the corresponding unsigned
3382 integer constant. TYPE must be a scalar or vector integer type. CST
3383 must be of scalar or vector floating-point type. Both CST and TYPE
3384 must be scalars, or vectors of the same number of elements. If the
3385 value won't fit in the integer type, the result is a
3386 :ref:`poison value <poisonvalues>`.
3387 ``fptosi (CST to TYPE)``
3388 Convert a floating-point constant to the corresponding signed
3389 integer constant. TYPE must be a scalar or vector integer type. CST
3390 must be of scalar or vector floating-point type. Both CST and TYPE
3391 must be scalars, or vectors of the same number of elements. If the
3392 value won't fit in the integer type, the result is a
3393 :ref:`poison value <poisonvalues>`.
3394 ``uitofp (CST to TYPE)``
3395 Convert an unsigned integer constant to the corresponding
3396 floating-point constant. TYPE must be a scalar or vector floating-point
3397 type. CST must be of scalar or vector integer type. Both CST and TYPE must
3398 be scalars, or vectors of the same number of elements.
3399 ``sitofp (CST to TYPE)``
3400 Convert a signed integer constant to the corresponding floating-point
3401 constant. TYPE must be a scalar or vector floating-point type.
3402 CST must be of scalar or vector integer type. Both CST and TYPE must
3403 be scalars, or vectors of the same number of elements.
3404 ``ptrtoint (CST to TYPE)``
3405 Perform the :ref:`ptrtoint operation <i_ptrtoint>` on constants.
3406 ``inttoptr (CST to TYPE)``
3407 Perform the :ref:`inttoptr operation <i_inttoptr>` on constants.
3408 This one is *really* dangerous!
3409 ``bitcast (CST to TYPE)``
3410 Convert a constant, CST, to another TYPE.
3411 The constraints of the operands are the same as those for the
3412 :ref:`bitcast instruction <i_bitcast>`.
3413 ``addrspacecast (CST to TYPE)``
3414 Convert a constant pointer or constant vector of pointer, CST, to another
3415 TYPE in a different address space. The constraints of the operands are the
3416 same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`.
3417 ``getelementptr (TY, CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (TY, CSTPTR, IDX0, IDX1, ...)``
3418 Perform the :ref:`getelementptr operation <i_getelementptr>` on
3419 constants. As with the :ref:`getelementptr <i_getelementptr>`
3420 instruction, the index list may have one or more indexes, which are
3421 required to make sense for the type of "pointer to TY".
3422 ``select (COND, VAL1, VAL2)``
3423 Perform the :ref:`select operation <i_select>` on constants.
3424 ``icmp COND (VAL1, VAL2)``
3425 Perform the :ref:`icmp operation <i_icmp>` on constants.
3426 ``fcmp COND (VAL1, VAL2)``
3427 Perform the :ref:`fcmp operation <i_fcmp>` on constants.
3428 ``extractelement (VAL, IDX)``
3429 Perform the :ref:`extractelement operation <i_extractelement>` on
3431 ``insertelement (VAL, ELT, IDX)``
3432 Perform the :ref:`insertelement operation <i_insertelement>` on
3434 ``shufflevector (VEC1, VEC2, IDXMASK)``
3435 Perform the :ref:`shufflevector operation <i_shufflevector>` on
3437 ``extractvalue (VAL, IDX0, IDX1, ...)``
3438 Perform the :ref:`extractvalue operation <i_extractvalue>` on
3439 constants. The index list is interpreted in a similar manner as
3440 indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At
3441 least one index value must be specified.
3442 ``insertvalue (VAL, ELT, IDX0, IDX1, ...)``
3443 Perform the :ref:`insertvalue operation <i_insertvalue>` on constants.
3444 The index list is interpreted in a similar manner as indices in a
3445 ':ref:`getelementptr <i_getelementptr>`' operation. At least one index
3446 value must be specified.
3447 ``OPCODE (LHS, RHS)``
3448 Perform the specified operation of the LHS and RHS constants. OPCODE
3449 may be any of the :ref:`binary <binaryops>` or :ref:`bitwise
3450 binary <bitwiseops>` operations. The constraints on operands are
3451 the same as those for the corresponding instruction (e.g. no bitwise
3452 operations on floating-point values are allowed).
3459 Inline Assembler Expressions
3460 ----------------------------
3462 LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level
3463 Inline Assembly <moduleasm>`) through the use of a special value. This value
3464 represents the inline assembler as a template string (containing the
3465 instructions to emit), a list of operand constraints (stored as a string), a
3466 flag that indicates whether or not the inline asm expression has side effects,
3467 and a flag indicating whether the function containing the asm needs to align its
3468 stack conservatively.
3470 The template string supports argument substitution of the operands using "``$``"
3471 followed by a number, to indicate substitution of the given register/memory
3472 location, as specified by the constraint string. "``${NUM:MODIFIER}``" may also
3473 be used, where ``MODIFIER`` is a target-specific annotation for how to print the
3474 operand (See :ref:`inline-asm-modifiers`).
3476 A literal "``$``" may be included by using "``$$``" in the template. To include
3477 other special characters into the output, the usual "``\XX``" escapes may be
3478 used, just as in other strings. Note that after template substitution, the
3479 resulting assembly string is parsed by LLVM's integrated assembler unless it is
3480 disabled -- even when emitting a ``.s`` file -- and thus must contain assembly
3481 syntax known to LLVM.
3483 LLVM also supports a few more substitions useful for writing inline assembly:
3485 - ``${:uid}``: Expands to a decimal integer unique to this inline assembly blob.
3486 This substitution is useful when declaring a local label. Many standard
3487 compiler optimizations, such as inlining, may duplicate an inline asm blob.
3488 Adding a blob-unique identifier ensures that the two labels will not conflict
3489 during assembly. This is used to implement `GCC's %= special format
3490 string <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_.
3491 - ``${:comment}``: Expands to the comment character of the current target's
3492 assembly dialect. This is usually ``#``, but many targets use other strings,
3493 such as ``;``, ``//``, or ``!``.
3494 - ``${:private}``: Expands to the assembler private label prefix. Labels with
3495 this prefix will not appear in the symbol table of the assembled object.
3496 Typically the prefix is ``L``, but targets may use other strings. ``.L`` is
3499 LLVM's support for inline asm is modeled closely on the requirements of Clang's
3500 GCC-compatible inline-asm support. Thus, the feature-set and the constraint and
3501 modifier codes listed here are similar or identical to those in GCC's inline asm
3502 support. However, to be clear, the syntax of the template and constraint strings
3503 described here is *not* the same as the syntax accepted by GCC and Clang, and,
3504 while most constraint letters are passed through as-is by Clang, some get
3505 translated to other codes when converting from the C source to the LLVM
3508 An example inline assembler expression is:
3510 .. code-block:: llvm
3512 i32 (i32) asm "bswap $0", "=r,r"
3514 Inline assembler expressions may **only** be used as the callee operand
3515 of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction.
3516 Thus, typically we have:
3518 .. code-block:: llvm
3520 %X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
3522 Inline asms with side effects not visible in the constraint list must be
3523 marked as having side effects. This is done through the use of the
3524 '``sideeffect``' keyword, like so:
3526 .. code-block:: llvm
3528 call void asm sideeffect "eieio", ""()
3530 In some cases inline asms will contain code that will not work unless
3531 the stack is aligned in some way, such as calls or SSE instructions on
3532 x86, yet will not contain code that does that alignment within the asm.
3533 The compiler should make conservative assumptions about what the asm
3534 might contain and should generate its usual stack alignment code in the
3535 prologue if the '``alignstack``' keyword is present:
3537 .. code-block:: llvm
3539 call void asm alignstack "eieio", ""()
3541 Inline asms also support using non-standard assembly dialects. The
3542 assumed dialect is ATT. When the '``inteldialect``' keyword is present,
3543 the inline asm is using the Intel dialect. Currently, ATT and Intel are
3544 the only supported dialects. An example is:
3546 .. code-block:: llvm
3548 call void asm inteldialect "eieio", ""()
3550 If multiple keywords appear the '``sideeffect``' keyword must come
3551 first, the '``alignstack``' keyword second and the '``inteldialect``'
3554 Inline Asm Constraint String
3555 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3557 The constraint list is a comma-separated string, each element containing one or
3558 more constraint codes.
3560 For each element in the constraint list an appropriate register or memory
3561 operand will be chosen, and it will be made available to assembly template
3562 string expansion as ``$0`` for the first constraint in the list, ``$1`` for the
3565 There are three different types of constraints, which are distinguished by a
3566 prefix symbol in front of the constraint code: Output, Input, and Clobber. The
3567 constraints must always be given in that order: outputs first, then inputs, then
3568 clobbers. They cannot be intermingled.
3570 There are also three different categories of constraint codes:
3572 - Register constraint. This is either a register class, or a fixed physical
3573 register. This kind of constraint will allocate a register, and if necessary,
3574 bitcast the argument or result to the appropriate type.
3575 - Memory constraint. This kind of constraint is for use with an instruction
3576 taking a memory operand. Different constraints allow for different addressing
3577 modes used by the target.
3578 - Immediate value constraint. This kind of constraint is for an integer or other
3579 immediate value which can be rendered directly into an instruction. The
3580 various target-specific constraints allow the selection of a value in the
3581 proper range for the instruction you wish to use it with.
3586 Output constraints are specified by an "``=``" prefix (e.g. "``=r``"). This
3587 indicates that the assembly will write to this operand, and the operand will
3588 then be made available as a return value of the ``asm`` expression. Output
3589 constraints do not consume an argument from the call instruction. (Except, see
3590 below about indirect outputs).
3592 Normally, it is expected that no output locations are written to by the assembly
3593 expression until *all* of the inputs have been read. As such, LLVM may assign
3594 the same register to an output and an input. If this is not safe (e.g. if the
3595 assembly contains two instructions, where the first writes to one output, and
3596 the second reads an input and writes to a second output), then the "``&``"
3597 modifier must be used (e.g. "``=&r``") to specify that the output is an
3598 "early-clobber" output. Marking an output as "early-clobber" ensures that LLVM
3599 will not use the same register for any inputs (other than an input tied to this
3605 Input constraints do not have a prefix -- just the constraint codes. Each input
3606 constraint will consume one argument from the call instruction. It is not
3607 permitted for the asm to write to any input register or memory location (unless
3608 that input is tied to an output). Note also that multiple inputs may all be
3609 assigned to the same register, if LLVM can determine that they necessarily all
3610 contain the same value.
3612 Instead of providing a Constraint Code, input constraints may also "tie"
3613 themselves to an output constraint, by providing an integer as the constraint
3614 string. Tied inputs still consume an argument from the call instruction, and
3615 take up a position in the asm template numbering as is usual -- they will simply
3616 be constrained to always use the same register as the output they've been tied
3617 to. For example, a constraint string of "``=r,0``" says to assign a register for
3618 output, and use that register as an input as well (it being the 0'th
3621 It is permitted to tie an input to an "early-clobber" output. In that case, no
3622 *other* input may share the same register as the input tied to the early-clobber
3623 (even when the other input has the same value).
3625 You may only tie an input to an output which has a register constraint, not a
3626 memory constraint. Only a single input may be tied to an output.
3628 There is also an "interesting" feature which deserves a bit of explanation: if a
3629 register class constraint allocates a register which is too small for the value
3630 type operand provided as input, the input value will be split into multiple
3631 registers, and all of them passed to the inline asm.
3633 However, this feature is often not as useful as you might think.
3635 Firstly, the registers are *not* guaranteed to be consecutive. So, on those
3636 architectures that have instructions which operate on multiple consecutive
3637 instructions, this is not an appropriate way to support them. (e.g. the 32-bit
3638 SparcV8 has a 64-bit load, which instruction takes a single 32-bit register. The
3639 hardware then loads into both the named register, and the next register. This
3640 feature of inline asm would not be useful to support that.)
3642 A few of the targets provide a template string modifier allowing explicit access
3643 to the second register of a two-register operand (e.g. MIPS ``L``, ``M``, and
3644 ``D``). On such an architecture, you can actually access the second allocated
3645 register (yet, still, not any subsequent ones). But, in that case, you're still
3646 probably better off simply splitting the value into two separate operands, for
3647 clarity. (e.g. see the description of the ``A`` constraint on X86, which,
3648 despite existing only for use with this feature, is not really a good idea to
3651 Indirect inputs and outputs
3652 """""""""""""""""""""""""""
3654 Indirect output or input constraints can be specified by the "``*``" modifier
3655 (which goes after the "``=``" in case of an output). This indicates that the asm
3656 will write to or read from the contents of an *address* provided as an input
3657 argument. (Note that in this way, indirect outputs act more like an *input* than
3658 an output: just like an input, they consume an argument of the call expression,
3659 rather than producing a return value. An indirect output constraint is an
3660 "output" only in that the asm is expected to write to the contents of the input
3661 memory location, instead of just read from it).
3663 This is most typically used for memory constraint, e.g. "``=*m``", to pass the
3664 address of a variable as a value.
3666 It is also possible to use an indirect *register* constraint, but only on output
3667 (e.g. "``=*r``"). This will cause LLVM to allocate a register for an output
3668 value normally, and then, separately emit a store to the address provided as
3669 input, after the provided inline asm. (It's not clear what value this
3670 functionality provides, compared to writing the store explicitly after the asm
3671 statement, and it can only produce worse code, since it bypasses many
3672 optimization passes. I would recommend not using it.)
3678 A clobber constraint is indicated by a "``~``" prefix. A clobber does not
3679 consume an input operand, nor generate an output. Clobbers cannot use any of the
3680 general constraint code letters -- they may use only explicit register
3681 constraints, e.g. "``~{eax}``". The one exception is that a clobber string of
3682 "``~{memory}``" indicates that the assembly writes to arbitrary undeclared
3683 memory locations -- not only the memory pointed to by a declared indirect
3686 Note that clobbering named registers that are also present in output
3687 constraints is not legal.
3692 After a potential prefix comes constraint code, or codes.
3694 A Constraint Code is either a single letter (e.g. "``r``"), a "``^``" character
3695 followed by two letters (e.g. "``^wc``"), or "``{``" register-name "``}``"
3698 The one and two letter constraint codes are typically chosen to be the same as
3699 GCC's constraint codes.
3701 A single constraint may include one or more than constraint code in it, leaving
3702 it up to LLVM to choose which one to use. This is included mainly for
3703 compatibility with the translation of GCC inline asm coming from clang.
3705 There are two ways to specify alternatives, and either or both may be used in an
3706 inline asm constraint list:
3708 1) Append the codes to each other, making a constraint code set. E.g. "``im``"
3709 or "``{eax}m``". This means "choose any of the options in the set". The
3710 choice of constraint is made independently for each constraint in the
3713 2) Use "``|``" between constraint code sets, creating alternatives. Every
3714 constraint in the constraint list must have the same number of alternative
3715 sets. With this syntax, the same alternative in *all* of the items in the
3716 constraint list will be chosen together.
3718 Putting those together, you might have a two operand constraint string like
3719 ``"rm|r,ri|rm"``. This indicates that if operand 0 is ``r`` or ``m``, then
3720 operand 1 may be one of ``r`` or ``i``. If operand 0 is ``r``, then operand 1
3721 may be one of ``r`` or ``m``. But, operand 0 and 1 cannot both be of type m.
3723 However, the use of either of the alternatives features is *NOT* recommended, as
3724 LLVM is not able to make an intelligent choice about which one to use. (At the
3725 point it currently needs to choose, not enough information is available to do so
3726 in a smart way.) Thus, it simply tries to make a choice that's most likely to
3727 compile, not one that will be optimal performance. (e.g., given "``rm``", it'll
3728 always choose to use memory, not registers). And, if given multiple registers,
3729 or multiple register classes, it will simply choose the first one. (In fact, it
3730 doesn't currently even ensure explicitly specified physical registers are
3731 unique, so specifying multiple physical registers as alternatives, like
3732 ``{r11}{r12},{r11}{r12}``, will assign r11 to both operands, not at all what was
3735 Supported Constraint Code List
3736 """"""""""""""""""""""""""""""
3738 The constraint codes are, in general, expected to behave the same way they do in
3739 GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C
3740 inline asm code which was supported by GCC. A mismatch in behavior between LLVM
3741 and GCC likely indicates a bug in LLVM.
3743 Some constraint codes are typically supported by all targets:
3745 - ``r``: A register in the target's general purpose register class.
3746 - ``m``: A memory address operand. It is target-specific what addressing modes
3747 are supported, typical examples are register, or register + register offset,
3748 or register + immediate offset (of some target-specific size).
3749 - ``i``: An integer constant (of target-specific width). Allows either a simple
3750 immediate, or a relocatable value.
3751 - ``n``: An integer constant -- *not* including relocatable values.
3752 - ``s``: An integer constant, but allowing *only* relocatable values.
3753 - ``X``: Allows an operand of any kind, no constraint whatsoever. Typically
3754 useful to pass a label for an asm branch or call.
3756 .. FIXME: but that surely isn't actually okay to jump out of an asm
3757 block without telling llvm about the control transfer???)
3759 - ``{register-name}``: Requires exactly the named physical register.
3761 Other constraints are target-specific:
3765 - ``z``: An immediate integer 0. Outputs ``WZR`` or ``XZR``, as appropriate.
3766 - ``I``: An immediate integer valid for an ``ADD`` or ``SUB`` instruction,
3767 i.e. 0 to 4095 with optional shift by 12.
3768 - ``J``: An immediate integer that, when negated, is valid for an ``ADD`` or
3769 ``SUB`` instruction, i.e. -1 to -4095 with optional left shift by 12.
3770 - ``K``: An immediate integer that is valid for the 'bitmask immediate 32' of a
3771 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 32-bit register.
3772 - ``L``: An immediate integer that is valid for the 'bitmask immediate 64' of a
3773 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 64-bit register.
3774 - ``M``: An immediate integer for use with the ``MOV`` assembly alias on a
3775 32-bit register. This is a superset of ``K``: in addition to the bitmask
3776 immediate, also allows immediate integers which can be loaded with a single
3777 ``MOVZ`` or ``MOVL`` instruction.
3778 - ``N``: An immediate integer for use with the ``MOV`` assembly alias on a
3779 64-bit register. This is a superset of ``L``.
3780 - ``Q``: Memory address operand must be in a single register (no
3781 offsets). (However, LLVM currently does this for the ``m`` constraint as
3783 - ``r``: A 32 or 64-bit integer register (W* or X*).
3784 - ``w``: A 32, 64, or 128-bit floating-point/SIMD register.
3785 - ``x``: A lower 128-bit floating-point/SIMD register (``V0`` to ``V15``).
3789 - ``r``: A 32 or 64-bit integer register.
3790 - ``[0-9]v``: The 32-bit VGPR register, number 0-9.
3791 - ``[0-9]s``: The 32-bit SGPR register, number 0-9.
3796 - ``Q``, ``Um``, ``Un``, ``Uq``, ``Us``, ``Ut``, ``Uv``, ``Uy``: Memory address
3797 operand. Treated the same as operand ``m``, at the moment.
3798 - ``Te``: An even general-purpose 32-bit integer register: ``r0,r2,...,r12,r14``
3799 - ``To``: An odd general-purpose 32-bit integer register: ``r1,r3,...,r11``
3801 ARM and ARM's Thumb2 mode:
3803 - ``j``: An immediate integer between 0 and 65535 (valid for ``MOVW``)
3804 - ``I``: An immediate integer valid for a data-processing instruction.
3805 - ``J``: An immediate integer between -4095 and 4095.
3806 - ``K``: An immediate integer whose bitwise inverse is valid for a
3807 data-processing instruction. (Can be used with template modifier "``B``" to
3808 print the inverted value).
3809 - ``L``: An immediate integer whose negation is valid for a data-processing
3810 instruction. (Can be used with template modifier "``n``" to print the negated
3812 - ``M``: A power of two or a integer between 0 and 32.
3813 - ``N``: Invalid immediate constraint.
3814 - ``O``: Invalid immediate constraint.
3815 - ``r``: A general-purpose 32-bit integer register (``r0-r15``).
3816 - ``l``: In Thumb2 mode, low 32-bit GPR registers (``r0-r7``). In ARM mode, same
3818 - ``h``: In Thumb2 mode, a high 32-bit GPR register (``r8-r15``). In ARM mode,
3820 - ``w``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s31``,
3821 ``d0-d31``, or ``q0-q15``.
3822 - ``x``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s15``,
3823 ``d0-d7``, or ``q0-q3``.
3824 - ``t``: A low floating-point/SIMD register: ``s0-s31``, ``d0-d16``, or
3829 - ``I``: An immediate integer between 0 and 255.
3830 - ``J``: An immediate integer between -255 and -1.
3831 - ``K``: An immediate integer between 0 and 255, with optional left-shift by
3833 - ``L``: An immediate integer between -7 and 7.
3834 - ``M``: An immediate integer which is a multiple of 4 between 0 and 1020.
3835 - ``N``: An immediate integer between 0 and 31.
3836 - ``O``: An immediate integer which is a multiple of 4 between -508 and 508.
3837 - ``r``: A low 32-bit GPR register (``r0-r7``).
3838 - ``l``: A low 32-bit GPR register (``r0-r7``).
3839 - ``h``: A high GPR register (``r0-r7``).
3840 - ``w``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s31``,
3841 ``d0-d31``, or ``q0-q15``.
3842 - ``x``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s15``,
3843 ``d0-d7``, or ``q0-q3``.
3844 - ``t``: A low floating-point/SIMD register: ``s0-s31``, ``d0-d16``, or
3850 - ``o``, ``v``: A memory address operand, treated the same as constraint ``m``,
3852 - ``r``: A 32 or 64-bit register.
3856 - ``r``: An 8 or 16-bit register.
3860 - ``I``: An immediate signed 16-bit integer.
3861 - ``J``: An immediate integer zero.
3862 - ``K``: An immediate unsigned 16-bit integer.
3863 - ``L``: An immediate 32-bit integer, where the lower 16 bits are 0.
3864 - ``N``: An immediate integer between -65535 and -1.
3865 - ``O``: An immediate signed 15-bit integer.
3866 - ``P``: An immediate integer between 1 and 65535.
3867 - ``m``: A memory address operand. In MIPS-SE mode, allows a base address
3868 register plus 16-bit immediate offset. In MIPS mode, just a base register.
3869 - ``R``: A memory address operand. In MIPS-SE mode, allows a base address
3870 register plus a 9-bit signed offset. In MIPS mode, the same as constraint
3872 - ``ZC``: A memory address operand, suitable for use in a ``pref``, ``ll``, or
3873 ``sc`` instruction on the given subtarget (details vary).
3874 - ``r``, ``d``, ``y``: A 32 or 64-bit GPR register.
3875 - ``f``: A 32 or 64-bit FPU register (``F0-F31``), or a 128-bit MSA register
3876 (``W0-W31``). In the case of MSA registers, it is recommended to use the ``w``
3877 argument modifier for compatibility with GCC.
3878 - ``c``: A 32-bit or 64-bit GPR register suitable for indirect jump (always
3880 - ``l``: The ``lo`` register, 32 or 64-bit.
3885 - ``b``: A 1-bit integer register.
3886 - ``c`` or ``h``: A 16-bit integer register.
3887 - ``r``: A 32-bit integer register.
3888 - ``l`` or ``N``: A 64-bit integer register.
3889 - ``f``: A 32-bit float register.
3890 - ``d``: A 64-bit float register.
3895 - ``I``: An immediate signed 16-bit integer.
3896 - ``J``: An immediate unsigned 16-bit integer, shifted left 16 bits.
3897 - ``K``: An immediate unsigned 16-bit integer.
3898 - ``L``: An immediate signed 16-bit integer, shifted left 16 bits.
3899 - ``M``: An immediate integer greater than 31.
3900 - ``N``: An immediate integer that is an exact power of 2.
3901 - ``O``: The immediate integer constant 0.
3902 - ``P``: An immediate integer constant whose negation is a signed 16-bit
3904 - ``es``, ``o``, ``Q``, ``Z``, ``Zy``: A memory address operand, currently
3905 treated the same as ``m``.
3906 - ``r``: A 32 or 64-bit integer register.
3907 - ``b``: A 32 or 64-bit integer register, excluding ``R0`` (that is:
3909 - ``f``: A 32 or 64-bit float register (``F0-F31``), or when QPX is enabled, a
3910 128 or 256-bit QPX register (``Q0-Q31``; aliases the ``F`` registers).
3911 - ``v``: For ``4 x f32`` or ``4 x f64`` types, when QPX is enabled, a
3912 128 or 256-bit QPX register (``Q0-Q31``), otherwise a 128-bit
3913 altivec vector register (``V0-V31``).
3915 .. FIXME: is this a bug that v accepts QPX registers? I think this
3916 is supposed to only use the altivec vector registers?
3918 - ``y``: Condition register (``CR0-CR7``).
3919 - ``wc``: An individual CR bit in a CR register.
3920 - ``wa``, ``wd``, ``wf``: Any 128-bit VSX vector register, from the full VSX
3921 register set (overlapping both the floating-point and vector register files).
3922 - ``ws``: A 32 or 64-bit floating-point register, from the full VSX register
3927 - ``I``: An immediate 13-bit signed integer.
3928 - ``r``: A 32-bit integer register.
3929 - ``f``: Any floating-point register on SparcV8, or a floating-point
3930 register in the "low" half of the registers on SparcV9.
3931 - ``e``: Any floating-point register. (Same as ``f`` on SparcV8.)
3935 - ``I``: An immediate unsigned 8-bit integer.
3936 - ``J``: An immediate unsigned 12-bit integer.
3937 - ``K``: An immediate signed 16-bit integer.
3938 - ``L``: An immediate signed 20-bit integer.
3939 - ``M``: An immediate integer 0x7fffffff.
3940 - ``Q``: A memory address operand with a base address and a 12-bit immediate
3941 unsigned displacement.
3942 - ``R``: A memory address operand with a base address, a 12-bit immediate
3943 unsigned displacement, and an index register.
3944 - ``S``: A memory address operand with a base address and a 20-bit immediate
3945 signed displacement.
3946 - ``T``: A memory address operand with a base address, a 20-bit immediate
3947 signed displacement, and an index register.
3948 - ``r`` or ``d``: A 32, 64, or 128-bit integer register.
3949 - ``a``: A 32, 64, or 128-bit integer address register (excludes R0, which in an
3950 address context evaluates as zero).
3951 - ``h``: A 32-bit value in the high part of a 64bit data register
3953 - ``f``: A 32, 64, or 128-bit floating-point register.
3957 - ``I``: An immediate integer between 0 and 31.
3958 - ``J``: An immediate integer between 0 and 64.
3959 - ``K``: An immediate signed 8-bit integer.
3960 - ``L``: An immediate integer, 0xff or 0xffff or (in 64-bit mode only)
3962 - ``M``: An immediate integer between 0 and 3.
3963 - ``N``: An immediate unsigned 8-bit integer.
3964 - ``O``: An immediate integer between 0 and 127.
3965 - ``e``: An immediate 32-bit signed integer.
3966 - ``Z``: An immediate 32-bit unsigned integer.
3967 - ``o``, ``v``: Treated the same as ``m``, at the moment.
3968 - ``q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit
3969 ``l`` integer register. On X86-32, this is the ``a``, ``b``, ``c``, and ``d``
3970 registers, and on X86-64, it is all of the integer registers.
3971 - ``Q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit
3972 ``h`` integer register. This is the ``a``, ``b``, ``c``, and ``d`` registers.
3973 - ``r`` or ``l``: An 8, 16, 32, or 64-bit integer register.
3974 - ``R``: An 8, 16, 32, or 64-bit "legacy" integer register -- one which has
3975 existed since i386, and can be accessed without the REX prefix.
3976 - ``f``: A 32, 64, or 80-bit '387 FPU stack pseudo-register.
3977 - ``y``: A 64-bit MMX register, if MMX is enabled.
3978 - ``x``: If SSE is enabled: a 32 or 64-bit scalar operand, or 128-bit vector
3979 operand in a SSE register. If AVX is also enabled, can also be a 256-bit
3980 vector operand in an AVX register. If AVX-512 is also enabled, can also be a
3981 512-bit vector operand in an AVX512 register, Otherwise, an error.
3982 - ``Y``: The same as ``x``, if *SSE2* is enabled, otherwise an error.
3983 - ``A``: Special case: allocates EAX first, then EDX, for a single operand (in
3984 32-bit mode, a 64-bit integer operand will get split into two registers). It
3985 is not recommended to use this constraint, as in 64-bit mode, the 64-bit
3986 operand will get allocated only to RAX -- if two 32-bit operands are needed,
3987 you're better off splitting it yourself, before passing it to the asm
3992 - ``r``: A 32-bit integer register.
3995 .. _inline-asm-modifiers:
3997 Asm template argument modifiers
3998 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4000 In the asm template string, modifiers can be used on the operand reference, like
4003 The modifiers are, in general, expected to behave the same way they do in
4004 GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C
4005 inline asm code which was supported by GCC. A mismatch in behavior between LLVM
4006 and GCC likely indicates a bug in LLVM.
4010 - ``c``: Print an immediate integer constant unadorned, without
4011 the target-specific immediate punctuation (e.g. no ``$`` prefix).
4012 - ``n``: Negate and print immediate integer constant unadorned, without the
4013 target-specific immediate punctuation (e.g. no ``$`` prefix).
4014 - ``l``: Print as an unadorned label, without the target-specific label
4015 punctuation (e.g. no ``$`` prefix).
4019 - ``w``: Print a GPR register with a ``w*`` name instead of ``x*`` name. E.g.,
4020 instead of ``x30``, print ``w30``.
4021 - ``x``: Print a GPR register with a ``x*`` name. (this is the default, anyhow).
4022 - ``b``, ``h``, ``s``, ``d``, ``q``: Print a floating-point/SIMD register with a
4023 ``b*``, ``h*``, ``s*``, ``d*``, or ``q*`` name, rather than the default of
4032 - ``a``: Print an operand as an address (with ``[`` and ``]`` surrounding a
4036 - ``y``: Print a VFP single-precision register as an indexed double (e.g. print
4037 as ``d4[1]`` instead of ``s9``)
4038 - ``B``: Bitwise invert and print an immediate integer constant without ``#``
4040 - ``L``: Print the low 16-bits of an immediate integer constant.
4041 - ``M``: Print as a register set suitable for ldm/stm. Also prints *all*
4042 register operands subsequent to the specified one (!), so use carefully.
4043 - ``Q``: Print the low-order register of a register-pair, or the low-order
4044 register of a two-register operand.
4045 - ``R``: Print the high-order register of a register-pair, or the high-order
4046 register of a two-register operand.
4047 - ``H``: Print the second register of a register-pair. (On a big-endian system,
4048 ``H`` is equivalent to ``Q``, and on little-endian system, ``H`` is equivalent
4051 .. FIXME: H doesn't currently support printing the second register
4052 of a two-register operand.
4054 - ``e``: Print the low doubleword register of a NEON quad register.
4055 - ``f``: Print the high doubleword register of a NEON quad register.
4056 - ``m``: Print the base register of a memory operand without the ``[`` and ``]``
4061 - ``L``: Print the second register of a two-register operand. Requires that it
4062 has been allocated consecutively to the first.
4064 .. FIXME: why is it restricted to consecutive ones? And there's
4065 nothing that ensures that happens, is there?
4067 - ``I``: Print the letter 'i' if the operand is an integer constant, otherwise
4068 nothing. Used to print 'addi' vs 'add' instructions.
4072 No additional modifiers.
4076 - ``X``: Print an immediate integer as hexadecimal
4077 - ``x``: Print the low 16 bits of an immediate integer as hexadecimal.
4078 - ``d``: Print an immediate integer as decimal.
4079 - ``m``: Subtract one and print an immediate integer as decimal.
4080 - ``z``: Print $0 if an immediate zero, otherwise print normally.
4081 - ``L``: Print the low-order register of a two-register operand, or prints the
4082 address of the low-order word of a double-word memory operand.
4084 .. FIXME: L seems to be missing memory operand support.
4086 - ``M``: Print the high-order register of a two-register operand, or prints the
4087 address of the high-order word of a double-word memory operand.
4089 .. FIXME: M seems to be missing memory operand support.
4091 - ``D``: Print the second register of a two-register operand, or prints the
4092 second word of a double-word memory operand. (On a big-endian system, ``D`` is
4093 equivalent to ``L``, and on little-endian system, ``D`` is equivalent to
4095 - ``w``: No effect. Provided for compatibility with GCC which requires this
4096 modifier in order to print MSA registers (``W0-W31``) with the ``f``
4105 - ``L``: Print the second register of a two-register operand. Requires that it
4106 has been allocated consecutively to the first.
4108 .. FIXME: why is it restricted to consecutive ones? And there's
4109 nothing that ensures that happens, is there?
4111 - ``I``: Print the letter 'i' if the operand is an integer constant, otherwise
4112 nothing. Used to print 'addi' vs 'add' instructions.
4113 - ``y``: For a memory operand, prints formatter for a two-register X-form
4114 instruction. (Currently always prints ``r0,OPERAND``).
4115 - ``U``: Prints 'u' if the memory operand is an update form, and nothing
4116 otherwise. (NOTE: LLVM does not support update form, so this will currently
4117 always print nothing)
4118 - ``X``: Prints 'x' if the memory operand is an indexed form. (NOTE: LLVM does
4119 not support indexed form, so this will currently always print nothing)
4127 SystemZ implements only ``n``, and does *not* support any of the other
4128 target-independent modifiers.
4132 - ``c``: Print an unadorned integer or symbol name. (The latter is
4133 target-specific behavior for this typically target-independent modifier).
4134 - ``A``: Print a register name with a '``*``' before it.
4135 - ``b``: Print an 8-bit register name (e.g. ``al``); do nothing on a memory
4137 - ``h``: Print the upper 8-bit register name (e.g. ``ah``); do nothing on a
4139 - ``w``: Print the 16-bit register name (e.g. ``ax``); do nothing on a memory
4141 - ``k``: Print the 32-bit register name (e.g. ``eax``); do nothing on a memory
4143 - ``q``: Print the 64-bit register name (e.g. ``rax``), if 64-bit registers are
4144 available, otherwise the 32-bit register name; do nothing on a memory operand.
4145 - ``n``: Negate and print an unadorned integer, or, for operands other than an
4146 immediate integer (e.g. a relocatable symbol expression), print a '-' before
4147 the operand. (The behavior for relocatable symbol expressions is a
4148 target-specific behavior for this typically target-independent modifier)
4149 - ``H``: Print a memory reference with additional offset +8.
4150 - ``P``: Print a memory reference or operand for use as the argument of a call
4151 instruction. (E.g. omit ``(rip)``, even though it's PC-relative.)
4155 No additional modifiers.
4161 The call instructions that wrap inline asm nodes may have a
4162 "``!srcloc``" MDNode attached to it that contains a list of constant
4163 integers. If present, the code generator will use the integer as the
4164 location cookie value when report errors through the ``LLVMContext``
4165 error reporting mechanisms. This allows a front-end to correlate backend
4166 errors that occur with inline asm back to the source code that produced
4169 .. code-block:: llvm
4171 call void asm sideeffect "something bad", ""(), !srcloc !42
4173 !42 = !{ i32 1234567 }
4175 It is up to the front-end to make sense of the magic numbers it places
4176 in the IR. If the MDNode contains multiple constants, the code generator
4177 will use the one that corresponds to the line of the asm that the error
4185 LLVM IR allows metadata to be attached to instructions in the program
4186 that can convey extra information about the code to the optimizers and
4187 code generator. One example application of metadata is source-level
4188 debug information. There are two metadata primitives: strings and nodes.
4190 Metadata does not have a type, and is not a value. If referenced from a
4191 ``call`` instruction, it uses the ``metadata`` type.
4193 All metadata are identified in syntax by a exclamation point ('``!``').
4195 .. _metadata-string:
4197 Metadata Nodes and Metadata Strings
4198 -----------------------------------
4200 A metadata string is a string surrounded by double quotes. It can
4201 contain any character by escaping non-printable characters with
4202 "``\xx``" where "``xx``" is the two digit hex code. For example:
4205 Metadata nodes are represented with notation similar to structure
4206 constants (a comma separated list of elements, surrounded by braces and
4207 preceded by an exclamation point). Metadata nodes can have any values as
4208 their operand. For example:
4210 .. code-block:: llvm
4212 !{ !"test\00", i32 10}
4214 Metadata nodes that aren't uniqued use the ``distinct`` keyword. For example:
4216 .. code-block:: text
4218 !0 = distinct !{!"test\00", i32 10}
4220 ``distinct`` nodes are useful when nodes shouldn't be merged based on their
4221 content. They can also occur when transformations cause uniquing collisions
4222 when metadata operands change.
4224 A :ref:`named metadata <namedmetadatastructure>` is a collection of
4225 metadata nodes, which can be looked up in the module symbol table. For
4228 .. code-block:: llvm
4232 Metadata can be used as function arguments. Here the ``llvm.dbg.value``
4233 intrinsic is using three metadata arguments:
4235 .. code-block:: llvm
4237 call void @llvm.dbg.value(metadata !24, metadata !25, metadata !26)
4239 Metadata can be attached to an instruction. Here metadata ``!21`` is attached
4240 to the ``add`` instruction using the ``!dbg`` identifier:
4242 .. code-block:: llvm
4244 %indvar.next = add i64 %indvar, 1, !dbg !21
4246 Metadata can also be attached to a function or a global variable. Here metadata
4247 ``!22`` is attached to the ``f1`` and ``f2 functions, and the globals ``g1``
4248 and ``g2`` using the ``!dbg`` identifier:
4250 .. code-block:: llvm
4252 declare !dbg !22 void @f1()
4253 define void @f2() !dbg !22 {
4257 @g1 = global i32 0, !dbg !22
4258 @g2 = external global i32, !dbg !22
4260 A transformation is required to drop any metadata attachment that it does not
4261 know or know it can't preserve. Currently there is an exception for metadata
4262 attachment to globals for ``!type`` and ``!absolute_symbol`` which can't be
4263 unconditionally dropped unless the global is itself deleted.
4265 Metadata attached to a module using named metadata may not be dropped, with
4266 the exception of debug metadata (named metadata with the name ``!llvm.dbg.*``).
4268 More information about specific metadata nodes recognized by the
4269 optimizers and code generator is found below.
4271 .. _specialized-metadata:
4273 Specialized Metadata Nodes
4274 ^^^^^^^^^^^^^^^^^^^^^^^^^^
4276 Specialized metadata nodes are custom data structures in metadata (as opposed
4277 to generic tuples). Their fields are labelled, and can be specified in any
4280 These aren't inherently debug info centric, but currently all the specialized
4281 metadata nodes are related to debug info.
4288 ``DICompileUnit`` nodes represent a compile unit. The ``enums:``,
4289 ``retainedTypes:``, ``globals:``, ``imports:`` and ``macros:`` fields are tuples
4290 containing the debug info to be emitted along with the compile unit, regardless
4291 of code optimizations (some nodes are only emitted if there are references to
4292 them from instructions). The ``debugInfoForProfiling:`` field is a boolean
4293 indicating whether or not line-table discriminators are updated to provide
4294 more-accurate debug info for profiling results.
4296 .. code-block:: text
4298 !0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang",
4299 isOptimized: true, flags: "-O2", runtimeVersion: 2,
4300 splitDebugFilename: "abc.debug", emissionKind: FullDebug,
4301 enums: !2, retainedTypes: !3, globals: !4, imports: !5,
4302 macros: !6, dwoId: 0x0abcd)
4304 Compile unit descriptors provide the root scope for objects declared in a
4305 specific compilation unit. File descriptors are defined using this scope. These
4306 descriptors are collected by a named metadata node ``!llvm.dbg.cu``. They keep
4307 track of global variables, type information, and imported entities (declarations
4315 ``DIFile`` nodes represent files. The ``filename:`` can include slashes.
4317 .. code-block:: none
4319 !0 = !DIFile(filename: "path/to/file", directory: "/path/to/dir",
4320 checksumkind: CSK_MD5,
4321 checksum: "000102030405060708090a0b0c0d0e0f")
4323 Files are sometimes used in ``scope:`` fields, and are the only valid target
4324 for ``file:`` fields.
4325 Valid values for ``checksumkind:`` field are: {CSK_None, CSK_MD5, CSK_SHA1}
4332 ``DIBasicType`` nodes represent primitive types, such as ``int``, ``bool`` and
4333 ``float``. ``tag:`` defaults to ``DW_TAG_base_type``.
4335 .. code-block:: text
4337 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8,
4338 encoding: DW_ATE_unsigned_char)
4339 !1 = !DIBasicType(tag: DW_TAG_unspecified_type, name: "decltype(nullptr)")
4341 The ``encoding:`` describes the details of the type. Usually it's one of the
4344 .. code-block:: text
4350 DW_ATE_signed_char = 6
4352 DW_ATE_unsigned_char = 8
4354 .. _DISubroutineType:
4359 ``DISubroutineType`` nodes represent subroutine types. Their ``types:`` field
4360 refers to a tuple; the first operand is the return type, while the rest are the
4361 types of the formal arguments in order. If the first operand is ``null``, that
4362 represents a function with no return value (such as ``void foo() {}`` in C++).
4364 .. code-block:: text
4366 !0 = !BasicType(name: "int", size: 32, align: 32, DW_ATE_signed)
4367 !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char)
4368 !2 = !DISubroutineType(types: !{null, !0, !1}) ; void (int, char)
4375 ``DIDerivedType`` nodes represent types derived from other types, such as
4378 .. code-block:: text
4380 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8,
4381 encoding: DW_ATE_unsigned_char)
4382 !1 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !0, size: 32,
4385 The following ``tag:`` values are valid:
4387 .. code-block:: text
4390 DW_TAG_pointer_type = 15
4391 DW_TAG_reference_type = 16
4393 DW_TAG_inheritance = 28
4394 DW_TAG_ptr_to_member_type = 31
4395 DW_TAG_const_type = 38
4397 DW_TAG_volatile_type = 53
4398 DW_TAG_restrict_type = 55
4399 DW_TAG_atomic_type = 71
4401 .. _DIDerivedTypeMember:
4403 ``DW_TAG_member`` is used to define a member of a :ref:`composite type
4404 <DICompositeType>`. The type of the member is the ``baseType:``. The
4405 ``offset:`` is the member's bit offset. If the composite type has an ODR
4406 ``identifier:`` and does not set ``flags: DIFwdDecl``, then the member is
4407 uniqued based only on its ``name:`` and ``scope:``.
4409 ``DW_TAG_inheritance`` and ``DW_TAG_friend`` are used in the ``elements:``
4410 field of :ref:`composite types <DICompositeType>` to describe parents and
4413 ``DW_TAG_typedef`` is used to provide a name for the ``baseType:``.
4415 ``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``,
4416 ``DW_TAG_volatile_type``, ``DW_TAG_restrict_type`` and ``DW_TAG_atomic_type``
4417 are used to qualify the ``baseType:``.
4419 Note that the ``void *`` type is expressed as a type derived from NULL.
4421 .. _DICompositeType:
4426 ``DICompositeType`` nodes represent types composed of other types, like
4427 structures and unions. ``elements:`` points to a tuple of the composed types.
4429 If the source language supports ODR, the ``identifier:`` field gives the unique
4430 identifier used for type merging between modules. When specified,
4431 :ref:`subprogram declarations <DISubprogramDeclaration>` and :ref:`member
4432 derived types <DIDerivedTypeMember>` that reference the ODR-type in their
4433 ``scope:`` change uniquing rules.
4435 For a given ``identifier:``, there should only be a single composite type that
4436 does not have ``flags: DIFlagFwdDecl`` set. LLVM tools that link modules
4437 together will unique such definitions at parse time via the ``identifier:``
4438 field, even if the nodes are ``distinct``.
4440 .. code-block:: text
4442 !0 = !DIEnumerator(name: "SixKind", value: 7)
4443 !1 = !DIEnumerator(name: "SevenKind", value: 7)
4444 !2 = !DIEnumerator(name: "NegEightKind", value: -8)
4445 !3 = !DICompositeType(tag: DW_TAG_enumeration_type, name: "Enum", file: !12,
4446 line: 2, size: 32, align: 32, identifier: "_M4Enum",
4447 elements: !{!0, !1, !2})
4449 The following ``tag:`` values are valid:
4451 .. code-block:: text
4453 DW_TAG_array_type = 1
4454 DW_TAG_class_type = 2
4455 DW_TAG_enumeration_type = 4
4456 DW_TAG_structure_type = 19
4457 DW_TAG_union_type = 23
4459 For ``DW_TAG_array_type``, the ``elements:`` should be :ref:`subrange
4460 descriptors <DISubrange>`, each representing the range of subscripts at that
4461 level of indexing. The ``DIFlagVector`` flag to ``flags:`` indicates that an
4462 array type is a native packed vector.
4464 For ``DW_TAG_enumeration_type``, the ``elements:`` should be :ref:`enumerator
4465 descriptors <DIEnumerator>`, each representing the definition of an enumeration
4466 value for the set. All enumeration type descriptors are collected in the
4467 ``enums:`` field of the :ref:`compile unit <DICompileUnit>`.
4469 For ``DW_TAG_structure_type``, ``DW_TAG_class_type``, and
4470 ``DW_TAG_union_type``, the ``elements:`` should be :ref:`derived types
4471 <DIDerivedType>` with ``tag: DW_TAG_member``, ``tag: DW_TAG_inheritance``, or
4472 ``tag: DW_TAG_friend``; or :ref:`subprograms <DISubprogram>` with
4473 ``isDefinition: false``.
4480 ``DISubrange`` nodes are the elements for ``DW_TAG_array_type`` variants of
4481 :ref:`DICompositeType`.
4483 - ``count: -1`` indicates an empty array.
4484 - ``count: !9`` describes the count with a :ref:`DILocalVariable`.
4485 - ``count: !11`` describes the count with a :ref:`DIGlobalVariable`.
4487 .. code-block:: text
4489 !0 = !DISubrange(count: 5, lowerBound: 0) ; array counting from 0
4490 !1 = !DISubrange(count: 5, lowerBound: 1) ; array counting from 1
4491 !2 = !DISubrange(count: -1) ; empty array.
4493 ; Scopes used in rest of example
4494 !6 = !DIFile(filename: "vla.c", directory: "/path/to/file")
4495 !7 = distinct !DICompileUnit(language: DW_LANG_C99, file: !6)
4496 !8 = distinct !DISubprogram(name: "foo", scope: !7, file: !6, line: 5)
4498 ; Use of local variable as count value
4499 !9 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed)
4500 !10 = !DILocalVariable(name: "count", scope: !8, file: !6, line: 42, type: !9)
4501 !11 = !DISubrange(count: !10, lowerBound: 0)
4503 ; Use of global variable as count value
4504 !12 = !DIGlobalVariable(name: "count", scope: !8, file: !6, line: 22, type: !9)
4505 !13 = !DISubrange(count: !12, lowerBound: 0)
4512 ``DIEnumerator`` nodes are the elements for ``DW_TAG_enumeration_type``
4513 variants of :ref:`DICompositeType`.
4515 .. code-block:: text
4517 !0 = !DIEnumerator(name: "SixKind", value: 7)
4518 !1 = !DIEnumerator(name: "SevenKind", value: 7)
4519 !2 = !DIEnumerator(name: "NegEightKind", value: -8)
4521 DITemplateTypeParameter
4522 """""""""""""""""""""""
4524 ``DITemplateTypeParameter`` nodes represent type parameters to generic source
4525 language constructs. They are used (optionally) in :ref:`DICompositeType` and
4526 :ref:`DISubprogram` ``templateParams:`` fields.
4528 .. code-block:: text
4530 !0 = !DITemplateTypeParameter(name: "Ty", type: !1)
4532 DITemplateValueParameter
4533 """"""""""""""""""""""""
4535 ``DITemplateValueParameter`` nodes represent value parameters to generic source
4536 language constructs. ``tag:`` defaults to ``DW_TAG_template_value_parameter``,
4537 but if specified can also be set to ``DW_TAG_GNU_template_template_param`` or
4538 ``DW_TAG_GNU_template_param_pack``. They are used (optionally) in
4539 :ref:`DICompositeType` and :ref:`DISubprogram` ``templateParams:`` fields.
4541 .. code-block:: text
4543 !0 = !DITemplateValueParameter(name: "Ty", type: !1, value: i32 7)
4548 ``DINamespace`` nodes represent namespaces in the source language.
4550 .. code-block:: text
4552 !0 = !DINamespace(name: "myawesomeproject", scope: !1, file: !2, line: 7)
4554 .. _DIGlobalVariable:
4559 ``DIGlobalVariable`` nodes represent global variables in the source language.
4561 .. code-block:: text
4563 @foo = global i32, !dbg !0
4564 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression())
4565 !1 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !2,
4566 file: !3, line: 7, type: !4, isLocal: true,
4567 isDefinition: false, declaration: !5)
4570 DIGlobalVariableExpression
4571 """"""""""""""""""""""""""
4573 ``DIGlobalVariableExpression`` nodes tie a :ref:`DIGlobalVariable` together
4574 with a :ref:`DIExpression`.
4576 .. code-block:: text
4578 @lower = global i32, !dbg !0
4579 @upper = global i32, !dbg !1
4580 !0 = !DIGlobalVariableExpression(
4582 expr: !DIExpression(DW_OP_LLVM_fragment, 0, 32)
4584 !1 = !DIGlobalVariableExpression(
4586 expr: !DIExpression(DW_OP_LLVM_fragment, 32, 32)
4588 !2 = !DIGlobalVariable(name: "split64", linkageName: "split64", scope: !3,
4589 file: !4, line: 8, type: !5, declaration: !6)
4591 All global variable expressions should be referenced by the `globals:` field of
4592 a :ref:`compile unit <DICompileUnit>`.
4599 ``DISubprogram`` nodes represent functions from the source language. A
4600 distinct ``DISubprogram`` may be attached to a function definition using
4601 ``!dbg`` metadata. A unique ``DISubprogram`` may be attached to a function
4602 declaration used for call site debug info. The ``variables:`` field points at
4603 :ref:`variables <DILocalVariable>` that must be retained, even if their IR
4604 counterparts are optimized out of the IR. The ``type:`` field must point at an
4605 :ref:`DISubroutineType`.
4607 .. _DISubprogramDeclaration:
4609 When ``isDefinition: false``, subprograms describe a declaration in the type
4610 tree as opposed to a definition of a function. If the scope is a composite
4611 type with an ODR ``identifier:`` and that does not set ``flags: DIFwdDecl``,
4612 then the subprogram declaration is uniqued based only on its ``linkageName:``
4615 .. code-block:: text
4617 define void @_Z3foov() !dbg !0 {
4621 !0 = distinct !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1,
4622 file: !2, line: 7, type: !3, isLocal: true,
4623 isDefinition: true, scopeLine: 8,
4625 virtuality: DW_VIRTUALITY_pure_virtual,
4626 virtualIndex: 10, flags: DIFlagPrototyped,
4627 isOptimized: true, unit: !5, templateParams: !6,
4628 declaration: !7, variables: !8, thrownTypes: !9)
4635 ``DILexicalBlock`` nodes describe nested blocks within a :ref:`subprogram
4636 <DISubprogram>`. The line number and column numbers are used to distinguish
4637 two lexical blocks at same depth. They are valid targets for ``scope:``
4640 .. code-block:: text
4642 !0 = distinct !DILexicalBlock(scope: !1, file: !2, line: 7, column: 35)
4644 Usually lexical blocks are ``distinct`` to prevent node merging based on
4647 .. _DILexicalBlockFile:
4652 ``DILexicalBlockFile`` nodes are used to discriminate between sections of a
4653 :ref:`lexical block <DILexicalBlock>`. The ``file:`` field can be changed to
4654 indicate textual inclusion, or the ``discriminator:`` field can be used to
4655 discriminate between control flow within a single block in the source language.
4657 .. code-block:: text
4659 !0 = !DILexicalBlock(scope: !3, file: !4, line: 7, column: 35)
4660 !1 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 0)
4661 !2 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 1)
4668 ``DILocation`` nodes represent source debug locations. The ``scope:`` field is
4669 mandatory, and points at an :ref:`DILexicalBlockFile`, an
4670 :ref:`DILexicalBlock`, or an :ref:`DISubprogram`.
4672 .. code-block:: text
4674 !0 = !DILocation(line: 2900, column: 42, scope: !1, inlinedAt: !2)
4676 .. _DILocalVariable:
4681 ``DILocalVariable`` nodes represent local variables in the source language. If
4682 the ``arg:`` field is set to non-zero, then this variable is a subprogram
4683 parameter, and it will be included in the ``variables:`` field of its
4684 :ref:`DISubprogram`.
4686 .. code-block:: text
4688 !0 = !DILocalVariable(name: "this", arg: 1, scope: !3, file: !2, line: 7,
4689 type: !3, flags: DIFlagArtificial)
4690 !1 = !DILocalVariable(name: "x", arg: 2, scope: !4, file: !2, line: 7,
4692 !2 = !DILocalVariable(name: "y", scope: !5, file: !2, line: 7, type: !3)
4699 ``DIExpression`` nodes represent expressions that are inspired by the DWARF
4700 expression language. They are used in :ref:`debug intrinsics<dbg_intrinsics>`
4701 (such as ``llvm.dbg.declare`` and ``llvm.dbg.value``) to describe how the
4702 referenced LLVM variable relates to the source language variable. Debug
4703 intrinsics are interpreted left-to-right: start by pushing the value/address
4704 operand of the intrinsic onto a stack, then repeatedly push and evaluate
4705 opcodes from the DIExpression until the final variable description is produced.
4707 The current supported opcode vocabulary is limited:
4709 - ``DW_OP_deref`` dereferences the top of the expression stack.
4710 - ``DW_OP_plus`` pops the last two entries from the expression stack, adds
4711 them together and appends the result to the expression stack.
4712 - ``DW_OP_minus`` pops the last two entries from the expression stack, subtracts
4713 the last entry from the second last entry and appends the result to the
4715 - ``DW_OP_plus_uconst, 93`` adds ``93`` to the working expression.
4716 - ``DW_OP_LLVM_fragment, 16, 8`` specifies the offset and size (``16`` and ``8``
4717 here, respectively) of the variable fragment from the working expression. Note
4718 that contrary to DW_OP_bit_piece, the offset is describing the location
4719 within the described source variable.
4720 - ``DW_OP_LLVM_convert, 16, DW_ATE_signed`` specifies a bit size and encoding
4721 (``16`` and ``DW_ATE_signed`` here, respectively) to which the top of the
4722 expression stack is to be converted. Maps into a ``DW_OP_convert`` operation
4723 that references a base type constructed from the supplied values.
4724 - ``DW_OP_LLVM_tag_offset, tag_offset`` specifies that a memory tag should be
4725 optionally applied to the pointer. The memory tag is derived from the
4726 given tag offset in an implementation-defined manner.
4727 - ``DW_OP_swap`` swaps top two stack entries.
4728 - ``DW_OP_xderef`` provides extended dereference mechanism. The entry at the top
4729 of the stack is treated as an address. The second stack entry is treated as an
4730 address space identifier.
4731 - ``DW_OP_stack_value`` marks a constant value.
4733 DWARF specifies three kinds of simple location descriptions: Register, memory,
4734 and implicit location descriptions. Note that a location description is
4735 defined over certain ranges of a program, i.e the location of a variable may
4736 change over the course of the program. Register and memory location
4737 descriptions describe the *concrete location* of a source variable (in the
4738 sense that a debugger might modify its value), whereas *implicit locations*
4739 describe merely the actual *value* of a source variable which might not exist
4740 in registers or in memory (see ``DW_OP_stack_value``).
4742 A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect
4743 value (the address) of a source variable. The first operand of the intrinsic
4744 must be an address of some kind. A DIExpression attached to the intrinsic
4745 refines this address to produce a concrete location for the source variable.
4747 A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable.
4748 The first operand of the intrinsic may be a direct or indirect value. A
4749 DIExpresion attached to the intrinsic refines the first operand to produce a
4750 direct value. For example, if the first operand is an indirect value, it may be
4751 necessary to insert ``DW_OP_deref`` into the DIExpresion in order to produce a
4752 valid debug intrinsic.
4756 A DIExpression is interpreted in the same way regardless of which kind of
4757 debug intrinsic it's attached to.
4759 .. code-block:: text
4761 !0 = !DIExpression(DW_OP_deref)
4762 !1 = !DIExpression(DW_OP_plus_uconst, 3)
4763 !1 = !DIExpression(DW_OP_constu, 3, DW_OP_plus)
4764 !2 = !DIExpression(DW_OP_bit_piece, 3, 7)
4765 !3 = !DIExpression(DW_OP_deref, DW_OP_constu, 3, DW_OP_plus, DW_OP_LLVM_fragment, 3, 7)
4766 !4 = !DIExpression(DW_OP_constu, 2, DW_OP_swap, DW_OP_xderef)
4767 !5 = !DIExpression(DW_OP_constu, 42, DW_OP_stack_value)
4772 These flags encode various properties of DINodes.
4774 The `ArgumentNotModified` flag marks a function argument whose value
4775 is not modified throughout of a function. This flag is used to decide
4776 whether a DW_OP_entry_value can be used in a location description
4777 after the function prologue. The language frontend is expected to compute
4778 this property for each DILocalVariable. The flag should be used
4779 only in optimized code.
4784 ``DIObjCProperty`` nodes represent Objective-C property nodes.
4786 .. code-block:: text
4788 !3 = !DIObjCProperty(name: "foo", file: !1, line: 7, setter: "setFoo",
4789 getter: "getFoo", attributes: 7, type: !2)
4794 ``DIImportedEntity`` nodes represent entities (such as modules) imported into a
4797 .. code-block:: text
4799 !2 = !DIImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0,
4800 entity: !1, line: 7)
4805 ``DIMacro`` nodes represent definition or undefinition of a macro identifiers.
4806 The ``name:`` field is the macro identifier, followed by macro parameters when
4807 defining a function-like macro, and the ``value`` field is the token-string
4808 used to expand the macro identifier.
4810 .. code-block:: text
4812 !2 = !DIMacro(macinfo: DW_MACINFO_define, line: 7, name: "foo(x)",
4814 !3 = !DIMacro(macinfo: DW_MACINFO_undef, line: 30, name: "foo")
4819 ``DIMacroFile`` nodes represent inclusion of source files.
4820 The ``nodes:`` field is a list of ``DIMacro`` and ``DIMacroFile`` nodes that
4821 appear in the included source file.
4823 .. code-block:: text
4825 !2 = !DIMacroFile(macinfo: DW_MACINFO_start_file, line: 7, file: !2,
4831 In LLVM IR, memory does not have types, so LLVM's own type system is not
4832 suitable for doing type based alias analysis (TBAA). Instead, metadata is
4833 added to the IR to describe a type system of a higher level language. This
4834 can be used to implement C/C++ strict type aliasing rules, but it can also
4835 be used to implement custom alias analysis behavior for other languages.
4837 This description of LLVM's TBAA system is broken into two parts:
4838 :ref:`Semantics<tbaa_node_semantics>` talks about high level issues, and
4839 :ref:`Representation<tbaa_node_representation>` talks about the metadata
4840 encoding of various entities.
4842 It is always possible to trace any TBAA node to a "root" TBAA node (details
4843 in the :ref:`Representation<tbaa_node_representation>` section). TBAA
4844 nodes with different roots have an unknown aliasing relationship, and LLVM
4845 conservatively infers ``MayAlias`` between them. The rules mentioned in
4846 this section only pertain to TBAA nodes living under the same root.
4848 .. _tbaa_node_semantics:
4853 The TBAA metadata system, referred to as "struct path TBAA" (not to be
4854 confused with ``tbaa.struct``), consists of the following high level
4855 concepts: *Type Descriptors*, further subdivided into scalar type
4856 descriptors and struct type descriptors; and *Access Tags*.
4858 **Type descriptors** describe the type system of the higher level language
4859 being compiled. **Scalar type descriptors** describe types that do not
4860 contain other types. Each scalar type has a parent type, which must also
4861 be a scalar type or the TBAA root. Via this parent relation, scalar types
4862 within a TBAA root form a tree. **Struct type descriptors** denote types
4863 that contain a sequence of other type descriptors, at known offsets. These
4864 contained type descriptors can either be struct type descriptors themselves
4865 or scalar type descriptors.
4867 **Access tags** are metadata nodes attached to load and store instructions.
4868 Access tags use type descriptors to describe the *location* being accessed
4869 in terms of the type system of the higher level language. Access tags are
4870 tuples consisting of a base type, an access type and an offset. The base
4871 type is a scalar type descriptor or a struct type descriptor, the access
4872 type is a scalar type descriptor, and the offset is a constant integer.
4874 The access tag ``(BaseTy, AccessTy, Offset)`` can describe one of two
4877 * If ``BaseTy`` is a struct type, the tag describes a memory access (load
4878 or store) of a value of type ``AccessTy`` contained in the struct type
4879 ``BaseTy`` at offset ``Offset``.
4881 * If ``BaseTy`` is a scalar type, ``Offset`` must be 0 and ``BaseTy`` and
4882 ``AccessTy`` must be the same; and the access tag describes a scalar
4883 access with scalar type ``AccessTy``.
4885 We first define an ``ImmediateParent`` relation on ``(BaseTy, Offset)``
4888 * If ``BaseTy`` is a scalar type then ``ImmediateParent(BaseTy, 0)`` is
4889 ``(ParentTy, 0)`` where ``ParentTy`` is the parent of the scalar type as
4890 described in the TBAA metadata. ``ImmediateParent(BaseTy, Offset)`` is
4891 undefined if ``Offset`` is non-zero.
4893 * If ``BaseTy`` is a struct type then ``ImmediateParent(BaseTy, Offset)``
4894 is ``(NewTy, NewOffset)`` where ``NewTy`` is the type contained in
4895 ``BaseTy`` at offset ``Offset`` and ``NewOffset`` is ``Offset`` adjusted
4896 to be relative within that inner type.
4898 A memory access with an access tag ``(BaseTy1, AccessTy1, Offset1)``
4899 aliases a memory access with an access tag ``(BaseTy2, AccessTy2,
4900 Offset2)`` if either ``(BaseTy1, Offset1)`` is reachable from ``(Base2,
4901 Offset2)`` via the ``Parent`` relation or vice versa.
4903 As a concrete example, the type descriptor graph for the following program
4909 float f; // offset 4
4913 float f; // offset 0
4914 double d; // offset 4
4915 struct Inner inner_a; // offset 12
4918 void f(struct Outer* outer, struct Inner* inner, float* f, int* i, char* c) {
4919 outer->f = 0; // tag0: (OuterStructTy, FloatScalarTy, 0)
4920 outer->inner_a.i = 0; // tag1: (OuterStructTy, IntScalarTy, 12)
4921 outer->inner_a.f = 0.0; // tag2: (OuterStructTy, FloatScalarTy, 16)
4922 *f = 0.0; // tag3: (FloatScalarTy, FloatScalarTy, 0)
4925 is (note that in C and C++, ``char`` can be used to access any arbitrary
4928 .. code-block:: text
4931 CharScalarTy = ("char", Root, 0)
4932 FloatScalarTy = ("float", CharScalarTy, 0)
4933 DoubleScalarTy = ("double", CharScalarTy, 0)
4934 IntScalarTy = ("int", CharScalarTy, 0)
4935 InnerStructTy = {"Inner" (IntScalarTy, 0), (FloatScalarTy, 4)}
4936 OuterStructTy = {"Outer", (FloatScalarTy, 0), (DoubleScalarTy, 4),
4937 (InnerStructTy, 12)}
4940 with (e.g.) ``ImmediateParent(OuterStructTy, 12)`` = ``(InnerStructTy,
4941 0)``, ``ImmediateParent(InnerStructTy, 0)`` = ``(IntScalarTy, 0)``, and
4942 ``ImmediateParent(IntScalarTy, 0)`` = ``(CharScalarTy, 0)``.
4944 .. _tbaa_node_representation:
4949 The root node of a TBAA type hierarchy is an ``MDNode`` with 0 operands or
4950 with exactly one ``MDString`` operand.
4952 Scalar type descriptors are represented as an ``MDNode`` s with two
4953 operands. The first operand is an ``MDString`` denoting the name of the
4954 struct type. LLVM does not assign meaning to the value of this operand, it
4955 only cares about it being an ``MDString``. The second operand is an
4956 ``MDNode`` which points to the parent for said scalar type descriptor,
4957 which is either another scalar type descriptor or the TBAA root. Scalar
4958 type descriptors can have an optional third argument, but that must be the
4959 constant integer zero.
4961 Struct type descriptors are represented as ``MDNode`` s with an odd number
4962 of operands greater than 1. The first operand is an ``MDString`` denoting
4963 the name of the struct type. Like in scalar type descriptors the actual
4964 value of this name operand is irrelevant to LLVM. After the name operand,
4965 the struct type descriptors have a sequence of alternating ``MDNode`` and
4966 ``ConstantInt`` operands. With N starting from 1, the 2N - 1 th operand,
4967 an ``MDNode``, denotes a contained field, and the 2N th operand, a
4968 ``ConstantInt``, is the offset of the said contained field. The offsets
4969 must be in non-decreasing order.
4971 Access tags are represented as ``MDNode`` s with either 3 or 4 operands.
4972 The first operand is an ``MDNode`` pointing to the node representing the
4973 base type. The second operand is an ``MDNode`` pointing to the node
4974 representing the access type. The third operand is a ``ConstantInt`` that
4975 states the offset of the access. If a fourth field is present, it must be
4976 a ``ConstantInt`` valued at 0 or 1. If it is 1 then the access tag states
4977 that the location being accessed is "constant" (meaning
4978 ``pointsToConstantMemory`` should return true; see `other useful
4979 AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_). The TBAA root of
4980 the access type and the base type of an access tag must be the same, and
4981 that is the TBAA root of the access tag.
4983 '``tbaa.struct``' Metadata
4984 ^^^^^^^^^^^^^^^^^^^^^^^^^^
4986 The :ref:`llvm.memcpy <int_memcpy>` is often used to implement
4987 aggregate assignment operations in C and similar languages, however it
4988 is defined to copy a contiguous region of memory, which is more than
4989 strictly necessary for aggregate types which contain holes due to
4990 padding. Also, it doesn't contain any TBAA information about the fields
4993 ``!tbaa.struct`` metadata can describe which memory subregions in a
4994 memcpy are padding and what the TBAA tags of the struct are.
4996 The current metadata format is very simple. ``!tbaa.struct`` metadata
4997 nodes are a list of operands which are in conceptual groups of three.
4998 For each group of three, the first operand gives the byte offset of a
4999 field in bytes, the second gives its size in bytes, and the third gives
5002 .. code-block:: llvm
5004 !4 = !{ i64 0, i64 4, !1, i64 8, i64 4, !2 }
5006 This describes a struct with two fields. The first is at offset 0 bytes
5007 with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
5008 and has size 4 bytes and has tbaa tag !2.
5010 Note that the fields need not be contiguous. In this example, there is a
5011 4 byte gap between the two fields. This gap represents padding which
5012 does not carry useful data and need not be preserved.
5014 '``noalias``' and '``alias.scope``' Metadata
5015 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5017 ``noalias`` and ``alias.scope`` metadata provide the ability to specify generic
5018 noalias memory-access sets. This means that some collection of memory access
5019 instructions (loads, stores, memory-accessing calls, etc.) that carry
5020 ``noalias`` metadata can specifically be specified not to alias with some other
5021 collection of memory access instructions that carry ``alias.scope`` metadata.
5022 Each type of metadata specifies a list of scopes where each scope has an id and
5025 When evaluating an aliasing query, if for some domain, the set
5026 of scopes with that domain in one instruction's ``alias.scope`` list is a
5027 subset of (or equal to) the set of scopes for that domain in another
5028 instruction's ``noalias`` list, then the two memory accesses are assumed not to
5031 Because scopes in one domain don't affect scopes in other domains, separate
5032 domains can be used to compose multiple independent noalias sets. This is
5033 used for example during inlining. As the noalias function parameters are
5034 turned into noalias scope metadata, a new domain is used every time the
5035 function is inlined.
5037 The metadata identifying each domain is itself a list containing one or two
5038 entries. The first entry is the name of the domain. Note that if the name is a
5039 string then it can be combined across functions and translation units. A
5040 self-reference can be used to create globally unique domain names. A
5041 descriptive string may optionally be provided as a second list entry.
5043 The metadata identifying each scope is also itself a list containing two or
5044 three entries. The first entry is the name of the scope. Note that if the name
5045 is a string then it can be combined across functions and translation units. A
5046 self-reference can be used to create globally unique scope names. A metadata
5047 reference to the scope's domain is the second entry. A descriptive string may
5048 optionally be provided as a third list entry.
5052 .. code-block:: llvm
5054 ; Two scope domains:
5058 ; Some scopes in these domains:
5064 !5 = !{!4} ; A list containing only scope !4
5068 ; These two instructions don't alias:
5069 %0 = load float, float* %c, align 4, !alias.scope !5
5070 store float %0, float* %arrayidx.i, align 4, !noalias !5
5072 ; These two instructions also don't alias (for domain !1, the set of scopes
5073 ; in the !alias.scope equals that in the !noalias list):
5074 %2 = load float, float* %c, align 4, !alias.scope !5
5075 store float %2, float* %arrayidx.i2, align 4, !noalias !6
5077 ; These two instructions may alias (for domain !0, the set of scopes in
5078 ; the !noalias list is not a superset of, or equal to, the scopes in the
5079 ; !alias.scope list):
5080 %2 = load float, float* %c, align 4, !alias.scope !6
5081 store float %0, float* %arrayidx.i, align 4, !noalias !7
5083 '``fpmath``' Metadata
5084 ^^^^^^^^^^^^^^^^^^^^^
5086 ``fpmath`` metadata may be attached to any instruction of floating-point
5087 type. It can be used to express the maximum acceptable error in the
5088 result of that instruction, in ULPs, thus potentially allowing the
5089 compiler to use a more efficient but less accurate method of computing
5090 it. ULP is defined as follows:
5092 If ``x`` is a real number that lies between two finite consecutive
5093 floating-point numbers ``a`` and ``b``, without being equal to one
5094 of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the
5095 distance between the two non-equal finite floating-point numbers
5096 nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``.
5098 The metadata node shall consist of a single positive float type number
5099 representing the maximum relative error, for example:
5101 .. code-block:: llvm
5103 !0 = !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
5107 '``range``' Metadata
5108 ^^^^^^^^^^^^^^^^^^^^
5110 ``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of
5111 integer types. It expresses the possible ranges the loaded value or the value
5112 returned by the called function at this call site is in. If the loaded or
5113 returned value is not in the specified range, the behavior is undefined. The
5114 ranges are represented with a flattened list of integers. The loaded value or
5115 the value returned is known to be in the union of the ranges defined by each
5116 consecutive pair. Each pair has the following properties:
5118 - The type must match the type loaded by the instruction.
5119 - The pair ``a,b`` represents the range ``[a,b)``.
5120 - Both ``a`` and ``b`` are constants.
5121 - The range is allowed to wrap.
5122 - The range should not represent the full or empty set. That is,
5125 In addition, the pairs must be in signed order of the lower bound and
5126 they must be non-contiguous.
5130 .. code-block:: llvm
5132 %a = load i8, i8* %x, align 1, !range !0 ; Can only be 0 or 1
5133 %b = load i8, i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
5134 %c = call i8 @foo(), !range !2 ; Can only be 0, 1, 3, 4 or 5
5135 %d = invoke i8 @bar() to label %cont
5136 unwind label %lpad, !range !3 ; Can only be -2, -1, 3, 4 or 5
5138 !0 = !{ i8 0, i8 2 }
5139 !1 = !{ i8 255, i8 2 }
5140 !2 = !{ i8 0, i8 2, i8 3, i8 6 }
5141 !3 = !{ i8 -2, i8 0, i8 3, i8 6 }
5143 '``absolute_symbol``' Metadata
5144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5146 ``absolute_symbol`` metadata may be attached to a global variable
5147 declaration. It marks the declaration as a reference to an absolute symbol,
5148 which causes the backend to use absolute relocations for the symbol even
5149 in position independent code, and expresses the possible ranges that the
5150 global variable's *address* (not its value) is in, in the same format as
5151 ``range`` metadata, with the extension that the pair ``all-ones,all-ones``
5152 may be used to represent the full set.
5154 Example (assuming 64-bit pointers):
5156 .. code-block:: llvm
5158 @a = external global i8, !absolute_symbol !0 ; Absolute symbol in range [0,256)
5159 @b = external global i8, !absolute_symbol !1 ; Absolute symbol in range [0,2^64)
5162 !0 = !{ i64 0, i64 256 }
5163 !1 = !{ i64 -1, i64 -1 }
5165 '``callees``' Metadata
5166 ^^^^^^^^^^^^^^^^^^^^^^
5168 ``callees`` metadata may be attached to indirect call sites. If ``callees``
5169 metadata is attached to a call site, and any callee is not among the set of
5170 functions provided by the metadata, the behavior is undefined. The intent of
5171 this metadata is to facilitate optimizations such as indirect-call promotion.
5172 For example, in the code below, the call instruction may only target the
5173 ``add`` or ``sub`` functions:
5175 .. code-block:: llvm
5177 %result = call i64 %binop(i64 %x, i64 %y), !callees !0
5180 !0 = !{i64 (i64, i64)* @add, i64 (i64, i64)* @sub}
5182 '``callback``' Metadata
5183 ^^^^^^^^^^^^^^^^^^^^^^^
5185 ``callback`` metadata may be attached to a function declaration, or definition.
5186 (Call sites are excluded only due to the lack of a use case.) For ease of
5187 exposition, we'll refer to the function annotated w/ metadata as a broker
5188 function. The metadata describes how the arguments of a call to the broker are
5189 in turn passed to the callback function specified by the metadata. Thus, the
5190 ``callback`` metadata provides a partial description of a call site inside the
5191 broker function with regards to the arguments of a call to the broker. The only
5192 semantic restriction on the broker function itself is that it is not allowed to
5193 inspect or modify arguments referenced in the ``callback`` metadata as
5194 pass-through to the callback function.
5196 The broker is not required to actually invoke the callback function at runtime.
5197 However, the assumptions about not inspecting or modifying arguments that would
5198 be passed to the specified callback function still hold, even if the callback
5199 function is not dynamically invoked. The broker is allowed to invoke the
5200 callback function more than once per invocation of the broker. The broker is
5201 also allowed to invoke (directly or indirectly) the function passed as a
5202 callback through another use. Finally, the broker is also allowed to relay the
5203 callback callee invocation to a different thread.
5205 The metadata is structured as follows: At the outer level, ``callback``
5206 metadata is a list of ``callback`` encodings. Each encoding starts with a
5207 constant ``i64`` which describes the argument position of the callback function
5208 in the call to the broker. The following elements, except the last, describe
5209 what arguments are passed to the callback function. Each element is again an
5210 ``i64`` constant identifying the argument of the broker that is passed through,
5211 or ``i64 -1`` to indicate an unknown or inspected argument. The order in which
5212 they are listed has to be the same in which they are passed to the callback
5213 callee. The last element of the encoding is a boolean which specifies how
5214 variadic arguments of the broker are handled. If it is true, all variadic
5215 arguments of the broker are passed through to the callback function *after* the
5216 arguments encoded explicitly before.
5218 In the code below, the ``pthread_create`` function is marked as a broker
5219 through the ``!callback !1`` metadata. In the example, there is only one
5220 callback encoding, namely ``!2``, associated with the broker. This encoding
5221 identifies the callback function as the second argument of the broker (``i64
5222 2``) and the sole argument of the callback function as the third one of the
5223 broker function (``i64 3``).
5225 .. FIXME why does the llvm-sphinx-docs builder give a highlighting
5226 error if the below is set to highlight as 'llvm', despite that we
5227 have misc.highlighting_failure set?
5229 .. code-block:: text
5231 declare !callback !1 dso_local i32 @pthread_create(i64*, %union.pthread_attr_t*, i8* (i8*)*, i8*)
5234 !2 = !{i64 2, i64 3, i1 false}
5237 Another example is shown below. The callback callee is the second argument of
5238 the ``__kmpc_fork_call`` function (``i64 2``). The callee is given two unknown
5239 values (each identified by a ``i64 -1``) and afterwards all
5240 variadic arguments that are passed to the ``__kmpc_fork_call`` call (due to the
5243 .. FIXME why does the llvm-sphinx-docs builder give a highlighting
5244 error if the below is set to highlight as 'llvm', despite that we
5245 have misc.highlighting_failure set?
5247 .. code-block:: text
5249 declare !callback !0 dso_local void @__kmpc_fork_call(%struct.ident_t*, i32, void (i32*, i32*, ...)*, ...)
5252 !1 = !{i64 2, i64 -1, i64 -1, i1 true}
5256 '``unpredictable``' Metadata
5257 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5259 ``unpredictable`` metadata may be attached to any branch or switch
5260 instruction. It can be used to express the unpredictability of control
5261 flow. Similar to the llvm.expect intrinsic, it may be used to alter
5262 optimizations related to compare and branch instructions. The metadata
5263 is treated as a boolean value; if it exists, it signals that the branch
5264 or switch that it is attached to is completely unpredictable.
5271 It is sometimes useful to attach information to loop constructs. Currently,
5272 loop metadata is implemented as metadata attached to the branch instruction
5273 in the loop latch block. This type of metadata refer to a metadata node that is
5274 guaranteed to be separate for each loop. The loop identifier metadata is
5275 specified with the name ``llvm.loop``.
5277 The loop identifier metadata is implemented using a metadata that refers to
5278 itself to avoid merging it with any other identifier metadata, e.g.,
5279 during module linkage or function inlining. That is, each loop should refer
5280 to their own identification metadata even if they reside in separate functions.
5281 The following example contains loop identifier metadata for two separate loop
5284 .. code-block:: llvm
5289 The loop identifier metadata can be used to specify additional
5290 per-loop metadata. Any operands after the first operand can be treated
5291 as user-defined metadata. For example the ``llvm.loop.unroll.count``
5292 suggests an unroll factor to the loop unroller:
5294 .. code-block:: llvm
5296 br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
5299 !1 = !{!"llvm.loop.unroll.count", i32 4}
5301 '``llvm.loop.disable_nonforced``'
5302 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5304 This metadata disables all optional loop transformations unless
5305 explicitly instructed using other transformation metdata such as
5306 ``llvm.loop.unroll.enable``. That is, no heuristic will try to determine
5307 whether a transformation is profitable. The purpose is to avoid that the
5308 loop is transformed to a different loop before an explicitly requested
5309 (forced) transformation is applied. For instance, loop fusion can make
5310 other transformations impossible. Mandatory loop canonicalizations such
5311 as loop rotation are still applied.
5313 It is recommended to use this metadata in addition to any llvm.loop.*
5314 transformation directive. Also, any loop should have at most one
5315 directive applied to it (and a sequence of transformations built using
5316 followup-attributes). Otherwise, which transformation will be applied
5317 depends on implementation details such as the pass pipeline order.
5319 See :ref:`transformation-metadata` for details.
5321 '``llvm.loop.vectorize``' and '``llvm.loop.interleave``'
5322 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5324 Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are
5325 used to control per-loop vectorization and interleaving parameters such as
5326 vectorization width and interleave count. These metadata should be used in
5327 conjunction with ``llvm.loop`` loop identification metadata. The
5328 ``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only
5329 optimization hints and the optimizer will only interleave and vectorize loops if
5330 it believes it is safe to do so. The ``llvm.loop.parallel_accesses`` metadata
5331 which contains information about loop-carried memory dependencies can be helpful
5332 in determining the safety of these transformations.
5334 '``llvm.loop.interleave.count``' Metadata
5335 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5337 This metadata suggests an interleave count to the loop interleaver.
5338 The first operand is the string ``llvm.loop.interleave.count`` and the
5339 second operand is an integer specifying the interleave count. For
5342 .. code-block:: llvm
5344 !0 = !{!"llvm.loop.interleave.count", i32 4}
5346 Note that setting ``llvm.loop.interleave.count`` to 1 disables interleaving
5347 multiple iterations of the loop. If ``llvm.loop.interleave.count`` is set to 0
5348 then the interleave count will be determined automatically.
5350 '``llvm.loop.vectorize.enable``' Metadata
5351 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5353 This metadata selectively enables or disables vectorization for the loop. The
5354 first operand is the string ``llvm.loop.vectorize.enable`` and the second operand
5355 is a bit. If the bit operand value is 1 vectorization is enabled. A value of
5356 0 disables vectorization:
5358 .. code-block:: llvm
5360 !0 = !{!"llvm.loop.vectorize.enable", i1 0}
5361 !1 = !{!"llvm.loop.vectorize.enable", i1 1}
5363 '``llvm.loop.vectorize.width``' Metadata
5364 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5366 This metadata sets the target width of the vectorizer. The first
5367 operand is the string ``llvm.loop.vectorize.width`` and the second
5368 operand is an integer specifying the width. For example:
5370 .. code-block:: llvm
5372 !0 = !{!"llvm.loop.vectorize.width", i32 4}
5374 Note that setting ``llvm.loop.vectorize.width`` to 1 disables
5375 vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to
5376 0 or if the loop does not have this metadata the width will be
5377 determined automatically.
5379 '``llvm.loop.vectorize.followup_vectorized``' Metadata
5380 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5382 This metadata defines which loop attributes the vectorized loop will
5383 have. See :ref:`transformation-metadata` for details.
5385 '``llvm.loop.vectorize.followup_epilogue``' Metadata
5386 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5388 This metadata defines which loop attributes the epilogue will have. The
5389 epilogue is not vectorized and is executed when either the vectorized
5390 loop is not known to preserve semantics (because e.g., it processes two
5391 arrays that are found to alias by a runtime check) or for the last
5392 iterations that do not fill a complete set of vector lanes. See
5393 :ref:`Transformation Metadata <transformation-metadata>` for details.
5395 '``llvm.loop.vectorize.followup_all``' Metadata
5396 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5398 Attributes in the metadata will be added to both the vectorized and
5400 See :ref:`Transformation Metadata <transformation-metadata>` for details.
5402 '``llvm.loop.unroll``'
5403 ^^^^^^^^^^^^^^^^^^^^^^
5405 Metadata prefixed with ``llvm.loop.unroll`` are loop unrolling
5406 optimization hints such as the unroll factor. ``llvm.loop.unroll``
5407 metadata should be used in conjunction with ``llvm.loop`` loop
5408 identification metadata. The ``llvm.loop.unroll`` metadata are only
5409 optimization hints and the unrolling will only be performed if the
5410 optimizer believes it is safe to do so.
5412 '``llvm.loop.unroll.count``' Metadata
5413 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5415 This metadata suggests an unroll factor to the loop unroller. The
5416 first operand is the string ``llvm.loop.unroll.count`` and the second
5417 operand is a positive integer specifying the unroll factor. For
5420 .. code-block:: llvm
5422 !0 = !{!"llvm.loop.unroll.count", i32 4}
5424 If the trip count of the loop is less than the unroll count the loop
5425 will be partially unrolled.
5427 '``llvm.loop.unroll.disable``' Metadata
5428 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5430 This metadata disables loop unrolling. The metadata has a single operand
5431 which is the string ``llvm.loop.unroll.disable``. For example:
5433 .. code-block:: llvm
5435 !0 = !{!"llvm.loop.unroll.disable"}
5437 '``llvm.loop.unroll.runtime.disable``' Metadata
5438 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5440 This metadata disables runtime loop unrolling. The metadata has a single
5441 operand which is the string ``llvm.loop.unroll.runtime.disable``. For example:
5443 .. code-block:: llvm
5445 !0 = !{!"llvm.loop.unroll.runtime.disable"}
5447 '``llvm.loop.unroll.enable``' Metadata
5448 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5450 This metadata suggests that the loop should be fully unrolled if the trip count
5451 is known at compile time and partially unrolled if the trip count is not known
5452 at compile time. The metadata has a single operand which is the string
5453 ``llvm.loop.unroll.enable``. For example:
5455 .. code-block:: llvm
5457 !0 = !{!"llvm.loop.unroll.enable"}
5459 '``llvm.loop.unroll.full``' Metadata
5460 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5462 This metadata suggests that the loop should be unrolled fully. The
5463 metadata has a single operand which is the string ``llvm.loop.unroll.full``.
5466 .. code-block:: llvm
5468 !0 = !{!"llvm.loop.unroll.full"}
5470 '``llvm.loop.unroll.followup``' Metadata
5471 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5473 This metadata defines which loop attributes the unrolled loop will have.
5474 See :ref:`Transformation Metadata <transformation-metadata>` for details.
5476 '``llvm.loop.unroll.followup_remainder``' Metadata
5477 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5479 This metadata defines which loop attributes the remainder loop after
5480 partial/runtime unrolling will have. See
5481 :ref:`Transformation Metadata <transformation-metadata>` for details.
5483 '``llvm.loop.unroll_and_jam``'
5484 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5486 This metadata is treated very similarly to the ``llvm.loop.unroll`` metadata
5487 above, but affect the unroll and jam pass. In addition any loop with
5488 ``llvm.loop.unroll`` metadata but no ``llvm.loop.unroll_and_jam`` metadata will
5489 disable unroll and jam (so ``llvm.loop.unroll`` metadata will be left to the
5490 unroller, plus ``llvm.loop.unroll.disable`` metadata will disable unroll and jam
5493 The metadata for unroll and jam otherwise is the same as for ``unroll``.
5494 ``llvm.loop.unroll_and_jam.enable``, ``llvm.loop.unroll_and_jam.disable`` and
5495 ``llvm.loop.unroll_and_jam.count`` do the same as for unroll.
5496 ``llvm.loop.unroll_and_jam.full`` is not supported. Again these are only hints
5497 and the normal safety checks will still be performed.
5499 '``llvm.loop.unroll_and_jam.count``' Metadata
5500 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5502 This metadata suggests an unroll and jam factor to use, similarly to
5503 ``llvm.loop.unroll.count``. The first operand is the string
5504 ``llvm.loop.unroll_and_jam.count`` and the second operand is a positive integer
5505 specifying the unroll factor. For example:
5507 .. code-block:: llvm
5509 !0 = !{!"llvm.loop.unroll_and_jam.count", i32 4}
5511 If the trip count of the loop is less than the unroll count the loop
5512 will be partially unroll and jammed.
5514 '``llvm.loop.unroll_and_jam.disable``' Metadata
5515 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5517 This metadata disables loop unroll and jamming. The metadata has a single
5518 operand which is the string ``llvm.loop.unroll_and_jam.disable``. For example:
5520 .. code-block:: llvm
5522 !0 = !{!"llvm.loop.unroll_and_jam.disable"}
5524 '``llvm.loop.unroll_and_jam.enable``' Metadata
5525 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5527 This metadata suggests that the loop should be fully unroll and jammed if the
5528 trip count is known at compile time and partially unrolled if the trip count is
5529 not known at compile time. The metadata has a single operand which is the
5530 string ``llvm.loop.unroll_and_jam.enable``. For example:
5532 .. code-block:: llvm
5534 !0 = !{!"llvm.loop.unroll_and_jam.enable"}
5536 '``llvm.loop.unroll_and_jam.followup_outer``' Metadata
5537 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5539 This metadata defines which loop attributes the outer unrolled loop will
5540 have. See :ref:`Transformation Metadata <transformation-metadata>` for
5543 '``llvm.loop.unroll_and_jam.followup_inner``' Metadata
5544 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5546 This metadata defines which loop attributes the inner jammed loop will
5547 have. See :ref:`Transformation Metadata <transformation-metadata>` for
5550 '``llvm.loop.unroll_and_jam.followup_remainder_outer``' Metadata
5551 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5553 This metadata defines which attributes the epilogue of the outer loop
5554 will have. This loop is usually unrolled, meaning there is no such
5555 loop. This attribute will be ignored in this case. See
5556 :ref:`Transformation Metadata <transformation-metadata>` for details.
5558 '``llvm.loop.unroll_and_jam.followup_remainder_inner``' Metadata
5559 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5561 This metadata defines which attributes the inner loop of the epilogue
5562 will have. The outer epilogue will usually be unrolled, meaning there
5563 can be multiple inner remainder loops. See
5564 :ref:`Transformation Metadata <transformation-metadata>` for details.
5566 '``llvm.loop.unroll_and_jam.followup_all``' Metadata
5567 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5569 Attributes specified in the metadata is added to all
5570 ``llvm.loop.unroll_and_jam.*`` loops. See
5571 :ref:`Transformation Metadata <transformation-metadata>` for details.
5573 '``llvm.loop.licm_versioning.disable``' Metadata
5574 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5576 This metadata indicates that the loop should not be versioned for the purpose
5577 of enabling loop-invariant code motion (LICM). The metadata has a single operand
5578 which is the string ``llvm.loop.licm_versioning.disable``. For example:
5580 .. code-block:: llvm
5582 !0 = !{!"llvm.loop.licm_versioning.disable"}
5584 '``llvm.loop.distribute.enable``' Metadata
5585 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5587 Loop distribution allows splitting a loop into multiple loops. Currently,
5588 this is only performed if the entire loop cannot be vectorized due to unsafe
5589 memory dependencies. The transformation will attempt to isolate the unsafe
5590 dependencies into their own loop.
5592 This metadata can be used to selectively enable or disable distribution of the
5593 loop. The first operand is the string ``llvm.loop.distribute.enable`` and the
5594 second operand is a bit. If the bit operand value is 1 distribution is
5595 enabled. A value of 0 disables distribution:
5597 .. code-block:: llvm
5599 !0 = !{!"llvm.loop.distribute.enable", i1 0}
5600 !1 = !{!"llvm.loop.distribute.enable", i1 1}
5602 This metadata should be used in conjunction with ``llvm.loop`` loop
5603 identification metadata.
5605 '``llvm.loop.distribute.followup_coincident``' Metadata
5606 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5608 This metadata defines which attributes extracted loops with no cyclic
5609 dependencies will have (i.e. can be vectorized). See
5610 :ref:`Transformation Metadata <transformation-metadata>` for details.
5612 '``llvm.loop.distribute.followup_sequential``' Metadata
5613 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5615 This metadata defines which attributes the isolated loops with unsafe
5616 memory dependencies will have. See
5617 :ref:`Transformation Metadata <transformation-metadata>` for details.
5619 '``llvm.loop.distribute.followup_fallback``' Metadata
5620 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5622 If loop versioning is necessary, this metadata defined the attributes
5623 the non-distributed fallback version will have. See
5624 :ref:`Transformation Metadata <transformation-metadata>` for details.
5626 '``llvm.loop.distribute.followup_all``' Metadata
5627 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5629 Thes attributes in this metdata is added to all followup loops of the
5630 loop distribution pass. See
5631 :ref:`Transformation Metadata <transformation-metadata>` for details.
5633 '``llvm.access.group``' Metadata
5634 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5636 ``llvm.access.group`` metadata can be attached to any instruction that
5637 potentially accesses memory. It can point to a single distinct metadata
5638 node, which we call access group. This node represents all memory access
5639 instructions referring to it via ``llvm.access.group``. When an
5640 instruction belongs to multiple access groups, it can also point to a
5641 list of accesses groups, illustrated by the following example.
5643 .. code-block:: llvm
5645 %val = load i32, i32* %arrayidx, !llvm.access.group !0
5651 It is illegal for the list node to be empty since it might be confused
5652 with an access group.
5654 The access group metadata node must be 'distinct' to avoid collapsing
5655 multiple access groups by content. A access group metadata node must
5656 always be empty which can be used to distinguish an access group
5657 metadata node from a list of access groups. Being empty avoids the
5658 situation that the content must be updated which, because metadata is
5659 immutable by design, would required finding and updating all references
5660 to the access group node.
5662 The access group can be used to refer to a memory access instruction
5663 without pointing to it directly (which is not possible in global
5664 metadata). Currently, the only metadata making use of it is
5665 ``llvm.loop.parallel_accesses``.
5667 '``llvm.loop.parallel_accesses``' Metadata
5668 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5670 The ``llvm.loop.parallel_accesses`` metadata refers to one or more
5671 access group metadata nodes (see ``llvm.access.group``). It denotes that
5672 no loop-carried memory dependence exist between it and other instructions
5673 in the loop with this metadata.
5675 Let ``m1`` and ``m2`` be two instructions that both have the
5676 ``llvm.access.group`` metadata to the access group ``g1``, respectively
5677 ``g2`` (which might be identical). If a loop contains both access groups
5678 in its ``llvm.loop.parallel_accesses`` metadata, then the compiler can
5679 assume that there is no dependency between ``m1`` and ``m2`` carried by
5680 this loop. Instructions that belong to multiple access groups are
5681 considered having this property if at least one of the access groups
5682 matches the ``llvm.loop.parallel_accesses`` list.
5684 If all memory-accessing instructions in a loop have
5685 ``llvm.loop.parallel_accesses`` metadata that refers to that loop, then the
5686 loop has no loop carried memory dependences and is considered to be a
5689 Note that if not all memory access instructions belong to an access
5690 group referred to by ``llvm.loop.parallel_accesses``, then the loop must
5691 not be considered trivially parallel. Additional
5692 memory dependence analysis is required to make that determination. As a fail
5693 safe mechanism, this causes loops that were originally parallel to be considered
5694 sequential (if optimization passes that are unaware of the parallel semantics
5695 insert new memory instructions into the loop body).
5697 Example of a loop that is considered parallel due to its correct use of
5698 both ``llvm.access.group`` and ``llvm.loop.parallel_accesses``
5701 .. code-block:: llvm
5705 %val0 = load i32, i32* %arrayidx, !llvm.access.group !1
5707 store i32 %val0, i32* %arrayidx1, !llvm.access.group !1
5709 br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0
5713 !0 = distinct !{!0, !{!"llvm.loop.parallel_accesses", !1}}
5716 It is also possible to have nested parallel loops:
5718 .. code-block:: llvm
5722 %val1 = load i32, i32* %arrayidx3, !llvm.access.group !4
5724 br label %inner.for.body
5728 %val0 = load i32, i32* %arrayidx1, !llvm.access.group !3
5730 store i32 %val0, i32* %arrayidx2, !llvm.access.group !3
5732 br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1
5736 store i32 %val1, i32* %arrayidx4, !llvm.access.group !4
5738 br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
5740 outer.for.end: ; preds = %for.body
5742 !1 = distinct !{!1, !{!"llvm.loop.parallel_accesses", !3}} ; metadata for the inner loop
5743 !2 = distinct !{!2, !{!"llvm.loop.parallel_accesses", !3, !4}} ; metadata for the outer loop
5744 !3 = distinct !{} ; access group for instructions in the inner loop (which are implicitly contained in outer loop as well)
5745 !4 = distinct !{} ; access group for instructions in the outer, but not the inner loop
5747 '``irr_loop``' Metadata
5748 ^^^^^^^^^^^^^^^^^^^^^^^
5750 ``irr_loop`` metadata may be attached to the terminator instruction of a basic
5751 block that's an irreducible loop header (note that an irreducible loop has more
5752 than once header basic blocks.) If ``irr_loop`` metadata is attached to the
5753 terminator instruction of a basic block that is not really an irreducible loop
5754 header, the behavior is undefined. The intent of this metadata is to improve the
5755 accuracy of the block frequency propagation. For example, in the code below, the
5756 block ``header0`` may have a loop header weight (relative to the other headers of
5757 the irreducible loop) of 100:
5759 .. code-block:: llvm
5763 br i1 %cmp, label %t1, label %t2, !irr_loop !0
5766 !0 = !{"loop_header_weight", i64 100}
5768 Irreducible loop header weights are typically based on profile data.
5770 '``invariant.group``' Metadata
5771 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5773 The experimental ``invariant.group`` metadata may be attached to
5774 ``load``/``store`` instructions referencing a single metadata with no entries.
5775 The existence of the ``invariant.group`` metadata on the instruction tells
5776 the optimizer that every ``load`` and ``store`` to the same pointer operand
5777 can be assumed to load or store the same
5778 value (but see the ``llvm.launder.invariant.group`` intrinsic which affects
5779 when two pointers are considered the same). Pointers returned by bitcast or
5780 getelementptr with only zero indices are considered the same.
5784 .. code-block:: llvm
5786 @unknownPtr = external global i8
5789 store i8 42, i8* %ptr, !invariant.group !0
5790 call void @foo(i8* %ptr)
5792 %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change
5793 call void @foo(i8* %ptr)
5795 %newPtr = call i8* @getPointer(i8* %ptr)
5796 %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr
5798 %unknownValue = load i8, i8* @unknownPtr
5799 store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42
5801 call void @foo(i8* %ptr)
5802 %newPtr2 = call i8* @llvm.launder.invariant.group(i8* %ptr)
5803 %d = load i8, i8* %newPtr2, !invariant.group !0 ; Can't step through launder.invariant.group to get value of %ptr
5806 declare void @foo(i8*)
5807 declare i8* @getPointer(i8*)
5808 declare i8* @llvm.launder.invariant.group(i8*)
5812 The invariant.group metadata must be dropped when replacing one pointer by
5813 another based on aliasing information. This is because invariant.group is tied
5814 to the SSA value of the pointer operand.
5816 .. code-block:: llvm
5818 %v = load i8, i8* %x, !invariant.group !0
5819 ; if %x mustalias %y then we can replace the above instruction with
5820 %v = load i8, i8* %y
5822 Note that this is an experimental feature, which means that its semantics might
5823 change in the future.
5828 See :doc:`TypeMetadata`.
5830 '``associated``' Metadata
5831 ^^^^^^^^^^^^^^^^^^^^^^^^^
5833 The ``associated`` metadata may be attached to a global object
5834 declaration with a single argument that references another global object.
5836 This metadata prevents discarding of the global object in linker GC
5837 unless the referenced object is also discarded. The linker support for
5838 this feature is spotty. For best compatibility, globals carrying this
5841 - Be in a comdat with the referenced global.
5842 - Be in @llvm.compiler.used.
5843 - Have an explicit section with a name which is a valid C identifier.
5845 It does not have any effect on non-ELF targets.
5849 .. code-block:: text
5852 @a = global i32 1, comdat $a
5853 @b = internal global i32 2, comdat $a, section "abc", !associated !0
5860 The ``prof`` metadata is used to record profile data in the IR.
5861 The first operand of the metadata node indicates the profile metadata
5862 type. There are currently 3 types:
5863 :ref:`branch_weights<prof_node_branch_weights>`,
5864 :ref:`function_entry_count<prof_node_function_entry_count>`, and
5865 :ref:`VP<prof_node_VP>`.
5867 .. _prof_node_branch_weights:
5872 Branch weight metadata attached to a branch, select, switch or call instruction
5873 represents the likeliness of the associated branch being taken.
5874 For more information, see :doc:`BranchWeightMetadata`.
5876 .. _prof_node_function_entry_count:
5878 function_entry_count
5879 """"""""""""""""""""
5881 Function entry count metadata can be attached to function definitions
5882 to record the number of times the function is called. Used with BFI
5883 information, it is also used to derive the basic block profile count.
5884 For more information, see :doc:`BranchWeightMetadata`.
5891 VP (value profile) metadata can be attached to instructions that have
5892 value profile information. Currently this is indirect calls (where it
5893 records the hottest callees) and calls to memory intrinsics such as memcpy,
5894 memmove, and memset (where it records the hottest byte lengths).
5896 Each VP metadata node contains "VP" string, then a uint32_t value for the value
5897 profiling kind, a uint64_t value for the total number of times the instruction
5898 is executed, followed by uint64_t value and execution count pairs.
5899 The value profiling kind is 0 for indirect call targets and 1 for memory
5900 operations. For indirect call targets, each profile value is a hash
5901 of the callee function name, and for memory operations each value is the
5904 Note that the value counts do not need to add up to the total count
5905 listed in the third operand (in practice only the top hottest values
5906 are tracked and reported).
5908 Indirect call example:
5910 .. code-block:: llvm
5912 call void %f(), !prof !1
5913 !1 = !{!"VP", i32 0, i64 1600, i64 7651369219802541373, i64 1030, i64 -4377547752858689819, i64 410}
5915 Note that the VP type is 0 (the second operand), which indicates this is
5916 an indirect call value profile data. The third operand indicates that the
5917 indirect call executed 1600 times. The 4th and 6th operands give the
5918 hashes of the 2 hottest target functions' names (this is the same hash used
5919 to represent function names in the profile database), and the 5th and 7th
5920 operands give the execution count that each of the respective prior target
5921 functions was called.
5923 Module Flags Metadata
5924 =====================
5926 Information about the module as a whole is difficult to convey to LLVM's
5927 subsystems. The LLVM IR isn't sufficient to transmit this information.
5928 The ``llvm.module.flags`` named metadata exists in order to facilitate
5929 this. These flags are in the form of key / value pairs --- much like a
5930 dictionary --- making it easy for any subsystem who cares about a flag to
5933 The ``llvm.module.flags`` metadata contains a list of metadata triplets.
5934 Each triplet has the following form:
5936 - The first element is a *behavior* flag, which specifies the behavior
5937 when two (or more) modules are merged together, and it encounters two
5938 (or more) metadata with the same ID. The supported behaviors are
5940 - The second element is a metadata string that is a unique ID for the
5941 metadata. Each module may only have one flag entry for each unique ID (not
5942 including entries with the **Require** behavior).
5943 - The third element is the value of the flag.
5945 When two (or more) modules are merged together, the resulting
5946 ``llvm.module.flags`` metadata is the union of the modules' flags. That is, for
5947 each unique metadata ID string, there will be exactly one entry in the merged
5948 modules ``llvm.module.flags`` metadata table, and the value for that entry will
5949 be determined by the merge behavior flag, as described below. The only exception
5950 is that entries with the *Require* behavior are always preserved.
5952 The following behaviors are supported:
5963 Emits an error if two values disagree, otherwise the resulting value
5964 is that of the operands.
5968 Emits a warning if two values disagree. The result value will be the
5969 operand for the flag from the first module being linked.
5973 Adds a requirement that another module flag be present and have a
5974 specified value after linking is performed. The value must be a
5975 metadata pair, where the first element of the pair is the ID of the
5976 module flag to be restricted, and the second element of the pair is
5977 the value the module flag should be restricted to. This behavior can
5978 be used to restrict the allowable results (via triggering of an
5979 error) of linking IDs with the **Override** behavior.
5983 Uses the specified value, regardless of the behavior or value of the
5984 other module. If both modules specify **Override**, but the values
5985 differ, an error will be emitted.
5989 Appends the two values, which are required to be metadata nodes.
5993 Appends the two values, which are required to be metadata
5994 nodes. However, duplicate entries in the second list are dropped
5995 during the append operation.
5999 Takes the max of the two values, which are required to be integers.
6001 It is an error for a particular unique flag ID to have multiple behaviors,
6002 except in the case of **Require** (which adds restrictions on another metadata
6003 value) or **Override**.
6005 An example of module flags:
6007 .. code-block:: llvm
6009 !0 = !{ i32 1, !"foo", i32 1 }
6010 !1 = !{ i32 4, !"bar", i32 37 }
6011 !2 = !{ i32 2, !"qux", i32 42 }
6012 !3 = !{ i32 3, !"qux",
6017 !llvm.module.flags = !{ !0, !1, !2, !3 }
6019 - Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior
6020 if two or more ``!"foo"`` flags are seen is to emit an error if their
6021 values are not equal.
6023 - Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The
6024 behavior if two or more ``!"bar"`` flags are seen is to use the value
6027 - Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The
6028 behavior if two or more ``!"qux"`` flags are seen is to emit a
6029 warning if their values are not equal.
6031 - Metadata ``!3`` has the ID ``!"qux"`` and the value:
6037 The behavior is to emit an error if the ``llvm.module.flags`` does not
6038 contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
6041 Objective-C Garbage Collection Module Flags Metadata
6042 ----------------------------------------------------
6044 On the Mach-O platform, Objective-C stores metadata about garbage
6045 collection in a special section called "image info". The metadata
6046 consists of a version number and a bitmask specifying what types of
6047 garbage collection are supported (if any) by the file. If two or more
6048 modules are linked together their garbage collection metadata needs to
6049 be merged rather than appended together.
6051 The Objective-C garbage collection module flags metadata consists of the
6052 following key-value pairs:
6061 * - ``Objective-C Version``
6062 - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2.
6064 * - ``Objective-C Image Info Version``
6065 - **[Required]** --- The version of the image info section. Currently
6068 * - ``Objective-C Image Info Section``
6069 - **[Required]** --- The section to place the metadata. Valid values are
6070 ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and
6071 ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for
6072 Objective-C ABI version 2.
6074 * - ``Objective-C Garbage Collection``
6075 - **[Required]** --- Specifies whether garbage collection is supported or
6076 not. Valid values are 0, for no garbage collection, and 2, for garbage
6077 collection supported.
6079 * - ``Objective-C GC Only``
6080 - **[Optional]** --- Specifies that only garbage collection is supported.
6081 If present, its value must be 6. This flag requires that the
6082 ``Objective-C Garbage Collection`` flag have the value 2.
6084 Some important flag interactions:
6086 - If a module with ``Objective-C Garbage Collection`` set to 0 is
6087 merged with a module with ``Objective-C Garbage Collection`` set to
6088 2, then the resulting module has the
6089 ``Objective-C Garbage Collection`` flag set to 0.
6090 - A module with ``Objective-C Garbage Collection`` set to 0 cannot be
6091 merged with a module with ``Objective-C GC Only`` set to 6.
6093 C type width Module Flags Metadata
6094 ----------------------------------
6096 The ARM backend emits a section into each generated object file describing the
6097 options that it was compiled with (in a compiler-independent way) to prevent
6098 linking incompatible objects, and to allow automatic library selection. Some
6099 of these options are not visible at the IR level, namely wchar_t width and enum
6102 To pass this information to the backend, these options are encoded in module
6103 flags metadata, using the following key-value pairs:
6113 - * 0 --- sizeof(wchar_t) == 4
6114 * 1 --- sizeof(wchar_t) == 2
6117 - * 0 --- Enums are at least as large as an ``int``.
6118 * 1 --- Enums are stored in the smallest integer type which can
6119 represent all of its values.
6121 For example, the following metadata section specifies that the module was
6122 compiled with a ``wchar_t`` width of 4 bytes, and the underlying type of an
6123 enum is the smallest type which can represent all of its values::
6125 !llvm.module.flags = !{!0, !1}
6126 !0 = !{i32 1, !"short_wchar", i32 1}
6127 !1 = !{i32 1, !"short_enum", i32 0}
6129 Automatic Linker Flags Named Metadata
6130 =====================================
6132 Some targets support embedding of flags to the linker inside individual object
6133 files. Typically this is used in conjunction with language extensions which
6134 allow source files to contain linker command line options, and have these
6135 automatically be transmitted to the linker via object files.
6137 These flags are encoded in the IR using named metadata with the name
6138 ``!llvm.linker.options``. Each operand is expected to be a metadata node
6139 which should be a list of other metadata nodes, each of which should be a
6140 list of metadata strings defining linker options.
6142 For example, the following metadata section specifies two separate sets of
6143 linker options, presumably to link against ``libz`` and the ``Cocoa``
6147 !1 = !{ !"-framework", !"Cocoa" }
6148 !llvm.linker.options = !{ !0, !1 }
6150 The metadata encoding as lists of lists of options, as opposed to a collapsed
6151 list of options, is chosen so that the IR encoding can use multiple option
6152 strings to specify e.g., a single library, while still having that specifier be
6153 preserved as an atomic element that can be recognized by a target specific
6154 assembly writer or object file emitter.
6156 Each individual option is required to be either a valid option for the target's
6157 linker, or an option that is reserved by the target specific assembly writer or
6158 object file emitter. No other aspect of these options is defined by the IR.
6160 Dependent Libs Named Metadata
6161 =============================
6163 Some targets support embedding of strings into object files to indicate
6164 a set of libraries to add to the link. Typically this is used in conjunction
6165 with language extensions which allow source files to explicitly declare the
6166 libraries they depend on, and have these automatically be transmitted to the
6167 linker via object files.
6169 The list is encoded in the IR using named metadata with the name
6170 ``!llvm.dependent-libraries``. Each operand is expected to be a metadata node
6171 which should contain a single string operand.
6173 For example, the following metadata section contains two library specfiers::
6175 !0 = !{!"a library specifier"}
6176 !1 = !{!"another library specifier"}
6177 !llvm.dependent-libraries = !{ !0, !1 }
6179 Each library specifier will be handled independently by the consuming linker.
6180 The effect of the library specifiers are defined by the consuming linker.
6187 Compiling with `ThinLTO <https://clang.llvm.org/docs/ThinLTO.html>`_
6188 causes the building of a compact summary of the module that is emitted into
6189 the bitcode. The summary is emitted into the LLVM assembly and identified
6190 in syntax by a caret ('``^``').
6192 The summary is parsed into a bitcode output, along with the Module
6193 IR, via the "``llvm-as``" tool. Tools that parse the Module IR for the purposes
6194 of optimization (e.g. "``clang -x ir``" and "``opt``"), will ignore the
6195 summary entries (just as they currently ignore summary entries in a bitcode
6198 Eventually, the summary will be parsed into a ModuleSummaryIndex object under
6199 the same conditions where summary index is currently built from bitcode.
6200 Specifically, tools that test the Thin Link portion of a ThinLTO compile
6201 (i.e. llvm-lto and llvm-lto2), or when parsing a combined index
6202 for a distributed ThinLTO backend via clang's "``-fthinlto-index=<>``" flag
6203 (this part is not yet implemented, use llvm-as to create a bitcode object
6204 before feeding into thin link tools for now).
6206 There are currently 3 types of summary entries in the LLVM assembly:
6207 :ref:`module paths<module_path_summary>`,
6208 :ref:`global values<gv_summary>`, and
6209 :ref:`type identifiers<typeid_summary>`.
6211 .. _module_path_summary:
6213 Module Path Summary Entry
6214 -------------------------
6216 Each module path summary entry lists a module containing global values included
6217 in the summary. For a single IR module there will be one such entry, but
6218 in a combined summary index produced during the thin link, there will be
6219 one module path entry per linked module with summary.
6223 .. code-block:: text
6225 ^0 = module: (path: "/path/to/file.o", hash: (2468601609, 1329373163, 1565878005, 638838075, 3148790418))
6227 The ``path`` field is a string path to the bitcode file, and the ``hash``
6228 field is the 160-bit SHA-1 hash of the IR bitcode contents, used for
6229 incremental builds and caching.
6233 Global Value Summary Entry
6234 --------------------------
6236 Each global value summary entry corresponds to a global value defined or
6237 referenced by a summarized module.
6241 .. code-block:: text
6243 ^4 = gv: (name: "f"[, summaries: (Summary)[, (Summary)]*]?) ; guid = 14740650423002898831
6245 For declarations, there will not be a summary list. For definitions, a
6246 global value will contain a list of summaries, one per module containing
6247 a definition. There can be multiple entries in a combined summary index
6248 for symbols with weak linkage.
6250 Each ``Summary`` format will depend on whether the global value is a
6251 :ref:`function<function_summary>`, :ref:`variable<variable_summary>`, or
6252 :ref:`alias<alias_summary>`.
6254 .. _function_summary:
6259 If the global value is a function, the ``Summary`` entry will look like:
6261 .. code-block:: text
6263 function: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), insts: 2[, FuncFlags]?[, Calls]?[, TypeIdInfo]?[, Refs]?
6265 The ``module`` field includes the summary entry id for the module containing
6266 this definition, and the ``flags`` field contains information such as
6267 the linkage type, a flag indicating whether it is legal to import the
6268 definition, whether it is globally live and whether the linker resolved it
6269 to a local definition (the latter two are populated during the thin link).
6270 The ``insts`` field contains the number of IR instructions in the function.
6271 Finally, there are several optional fields: :ref:`FuncFlags<funcflags_summary>`,
6272 :ref:`Calls<calls_summary>`, :ref:`TypeIdInfo<typeidinfo_summary>`,
6273 :ref:`Refs<refs_summary>`.
6275 .. _variable_summary:
6277 Global Variable Summary
6278 ^^^^^^^^^^^^^^^^^^^^^^^
6280 If the global value is a variable, the ``Summary`` entry will look like:
6282 .. code-block:: text
6284 variable: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0)[, Refs]?
6286 The variable entry contains a subset of the fields in a
6287 :ref:`function summary <function_summary>`, see the descriptions there.
6294 If the global value is an alias, the ``Summary`` entry will look like:
6296 .. code-block:: text
6298 alias: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), aliasee: ^2)
6300 The ``module`` and ``flags`` fields are as described for a
6301 :ref:`function summary <function_summary>`. The ``aliasee`` field
6302 contains a reference to the global value summary entry of the aliasee.
6304 .. _funcflags_summary:
6309 The optional ``FuncFlags`` field looks like:
6311 .. code-block:: text
6313 funcFlags: (readNone: 0, readOnly: 0, noRecurse: 0, returnDoesNotAlias: 0)
6315 If unspecified, flags are assumed to hold the conservative ``false`` value of
6323 The optional ``Calls`` field looks like:
6325 .. code-block:: text
6327 calls: ((Callee)[, (Callee)]*)
6329 where each ``Callee`` looks like:
6331 .. code-block:: text
6333 callee: ^1[, hotness: None]?[, relbf: 0]?
6335 The ``callee`` refers to the summary entry id of the callee. At most one
6336 of ``hotness`` (which can take the values ``Unknown``, ``Cold``, ``None``,
6337 ``Hot``, and ``Critical``), and ``relbf`` (which holds the integer
6338 branch frequency relative to the entry frequency, scaled down by 2^8)
6339 may be specified. The defaults are ``Unknown`` and ``0``, respectively.
6346 The optional ``Refs`` field looks like:
6348 .. code-block:: text
6350 refs: ((Ref)[, (Ref)]*)
6352 where each ``Ref`` contains a reference to the summary id of the referenced
6353 value (e.g. ``^1``).
6355 .. _typeidinfo_summary:
6360 The optional ``TypeIdInfo`` field, used for
6361 `Control Flow Integrity <http://clang.llvm.org/docs/ControlFlowIntegrity.html>`_,
6364 .. code-block:: text
6366 typeIdInfo: [(TypeTests)]?[, (TypeTestAssumeVCalls)]?[, (TypeCheckedLoadVCalls)]?[, (TypeTestAssumeConstVCalls)]?[, (TypeCheckedLoadConstVCalls)]?
6368 These optional fields have the following forms:
6373 .. code-block:: text
6375 typeTests: (TypeIdRef[, TypeIdRef]*)
6377 Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>`
6378 by summary id or ``GUID``.
6380 TypeTestAssumeVCalls
6381 """"""""""""""""""""
6383 .. code-block:: text
6385 typeTestAssumeVCalls: (VFuncId[, VFuncId]*)
6387 Where each VFuncId has the format:
6389 .. code-block:: text
6391 vFuncId: (TypeIdRef, offset: 16)
6393 Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>`
6394 by summary id or ``GUID`` preceeded by a ``guid:`` tag.
6396 TypeCheckedLoadVCalls
6397 """""""""""""""""""""
6399 .. code-block:: text
6401 typeCheckedLoadVCalls: (VFuncId[, VFuncId]*)
6403 Where each VFuncId has the format described for ``TypeTestAssumeVCalls``.
6405 TypeTestAssumeConstVCalls
6406 """""""""""""""""""""""""
6408 .. code-block:: text
6410 typeTestAssumeConstVCalls: (ConstVCall[, ConstVCall]*)
6412 Where each ConstVCall has the format:
6414 .. code-block:: text
6416 (VFuncId, args: (Arg[, Arg]*))
6418 and where each VFuncId has the format described for ``TypeTestAssumeVCalls``,
6419 and each Arg is an integer argument number.
6421 TypeCheckedLoadConstVCalls
6422 """"""""""""""""""""""""""
6424 .. code-block:: text
6426 typeCheckedLoadConstVCalls: (ConstVCall[, ConstVCall]*)
6428 Where each ConstVCall has the format described for
6429 ``TypeTestAssumeConstVCalls``.
6433 Type ID Summary Entry
6434 ---------------------
6436 Each type id summary entry corresponds to a type identifier resolution
6437 which is generated during the LTO link portion of the compile when building
6438 with `Control Flow Integrity <http://clang.llvm.org/docs/ControlFlowIntegrity.html>`_,
6439 so these are only present in a combined summary index.
6443 .. code-block:: text
6445 ^4 = typeid: (name: "_ZTS1A", summary: (typeTestRes: (kind: allOnes, sizeM1BitWidth: 7[, alignLog2: 0]?[, sizeM1: 0]?[, bitMask: 0]?[, inlineBits: 0]?)[, WpdResolutions]?)) ; guid = 7004155349499253778
6447 The ``typeTestRes`` gives the type test resolution ``kind`` (which may
6448 be ``unsat``, ``byteArray``, ``inline``, ``single``, or ``allOnes``), and
6449 the ``size-1`` bit width. It is followed by optional flags, which default to 0,
6450 and an optional WpdResolutions (whole program devirtualization resolution)
6451 field that looks like:
6453 .. code-block:: text
6455 wpdResolutions: ((offset: 0, WpdRes)[, (offset: 1, WpdRes)]*
6457 where each entry is a mapping from the given byte offset to the whole-program
6458 devirtualization resolution WpdRes, that has one of the following formats:
6460 .. code-block:: text
6462 wpdRes: (kind: branchFunnel)
6463 wpdRes: (kind: singleImpl, singleImplName: "_ZN1A1nEi")
6464 wpdRes: (kind: indir)
6466 Additionally, each wpdRes has an optional ``resByArg`` field, which
6467 describes the resolutions for calls with all constant integer arguments:
6469 .. code-block:: text
6471 resByArg: (ResByArg[, ResByArg]*)
6475 .. code-block:: text
6477 args: (Arg[, Arg]*), byArg: (kind: UniformRetVal[, info: 0][, byte: 0][, bit: 0])
6479 Where the ``kind`` can be ``Indir``, ``UniformRetVal``, ``UniqueRetVal``
6480 or ``VirtualConstProp``. The ``info`` field is only used if the kind
6481 is ``UniformRetVal`` (indicates the uniform return value), or
6482 ``UniqueRetVal`` (holds the return value associated with the unique vtable
6483 (0 or 1)). The ``byte`` and ``bit`` fields are only used if the target does
6484 not support the use of absolute symbols to store constants.
6486 .. _intrinsicglobalvariables:
6488 Intrinsic Global Variables
6489 ==========================
6491 LLVM has a number of "magic" global variables that contain data that
6492 affect code generation or other IR semantics. These are documented here.
6493 All globals of this sort should have a section specified as
6494 "``llvm.metadata``". This section and all globals that start with
6495 "``llvm.``" are reserved for use by LLVM.
6499 The '``llvm.used``' Global Variable
6500 -----------------------------------
6502 The ``@llvm.used`` global is an array which has
6503 :ref:`appending linkage <linkage_appending>`. This array contains a list of
6504 pointers to named global variables, functions and aliases which may optionally
6505 have a pointer cast formed of bitcast or getelementptr. For example, a legal
6508 .. code-block:: llvm
6513 @llvm.used = appending global [2 x i8*] [
6515 i8* bitcast (i32* @Y to i8*)
6516 ], section "llvm.metadata"
6518 If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler,
6519 and linker are required to treat the symbol as if there is a reference to the
6520 symbol that it cannot see (which is why they have to be named). For example, if
6521 a variable has internal linkage and no references other than that from the
6522 ``@llvm.used`` list, it cannot be deleted. This is commonly used to represent
6523 references from inline asms and other things the compiler cannot "see", and
6524 corresponds to "``attribute((used))``" in GNU C.
6526 On some targets, the code generator must emit a directive to the
6527 assembler or object file to prevent the assembler and linker from
6528 molesting the symbol.
6530 .. _gv_llvmcompilerused:
6532 The '``llvm.compiler.used``' Global Variable
6533 --------------------------------------------
6535 The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used``
6536 directive, except that it only prevents the compiler from touching the
6537 symbol. On targets that support it, this allows an intelligent linker to
6538 optimize references to the symbol without being impeded as it would be
6541 This is a rare construct that should only be used in rare circumstances,
6542 and should not be exposed to source languages.
6544 .. _gv_llvmglobalctors:
6546 The '``llvm.global_ctors``' Global Variable
6547 -------------------------------------------
6549 .. code-block:: llvm
6551 %0 = type { i32, void ()*, i8* }
6552 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor, i8* @data }]
6554 The ``@llvm.global_ctors`` array contains a list of constructor
6555 functions, priorities, and an associated global or function.
6556 The functions referenced by this array will be called in ascending order
6557 of priority (i.e. lowest first) when the module is loaded. The order of
6558 functions with the same priority is not defined.
6560 If the third field is non-null, and points to a global variable
6561 or function, the initializer function will only run if the associated
6562 data from the current module is not discarded.
6564 .. _llvmglobaldtors:
6566 The '``llvm.global_dtors``' Global Variable
6567 -------------------------------------------
6569 .. code-block:: llvm
6571 %0 = type { i32, void ()*, i8* }
6572 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor, i8* @data }]
6574 The ``@llvm.global_dtors`` array contains a list of destructor
6575 functions, priorities, and an associated global or function.
6576 The functions referenced by this array will be called in descending
6577 order of priority (i.e. highest first) when the module is unloaded. The
6578 order of functions with the same priority is not defined.
6580 If the third field is non-null, and points to a global variable
6581 or function, the destructor function will only run if the associated
6582 data from the current module is not discarded.
6584 Instruction Reference
6585 =====================
6587 The LLVM instruction set consists of several different classifications
6588 of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
6589 instructions <binaryops>`, :ref:`bitwise binary
6590 instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
6591 :ref:`other instructions <otherops>`.
6595 Terminator Instructions
6596 -----------------------
6598 As mentioned :ref:`previously <functionstructure>`, every basic block in a
6599 program ends with a "Terminator" instruction, which indicates which
6600 block should be executed after the current block is finished. These
6601 terminator instructions typically yield a '``void``' value: they produce
6602 control flow, not values (the one exception being the
6603 ':ref:`invoke <i_invoke>`' instruction).
6605 The terminator instructions are: ':ref:`ret <i_ret>`',
6606 ':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
6607 ':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
6608 ':ref:`callbr <i_callbr>`'
6609 ':ref:`resume <i_resume>`', ':ref:`catchswitch <i_catchswitch>`',
6610 ':ref:`catchret <i_catchret>`',
6611 ':ref:`cleanupret <i_cleanupret>`',
6612 and ':ref:`unreachable <i_unreachable>`'.
6616 '``ret``' Instruction
6617 ^^^^^^^^^^^^^^^^^^^^^
6624 ret <type> <value> ; Return a value from a non-void function
6625 ret void ; Return from void function
6630 The '``ret``' instruction is used to return control flow (and optionally
6631 a value) from a function back to the caller.
6633 There are two forms of the '``ret``' instruction: one that returns a
6634 value and then causes control flow, and one that just causes control
6640 The '``ret``' instruction optionally accepts a single argument, the
6641 return value. The type of the return value must be a ':ref:`first
6642 class <t_firstclass>`' type.
6644 A function is not :ref:`well formed <wellformed>` if it has a non-void
6645 return type and contains a '``ret``' instruction with no return value or
6646 a return value with a type that does not match its type, or if it has a
6647 void return type and contains a '``ret``' instruction with a return
6653 When the '``ret``' instruction is executed, control flow returns back to
6654 the calling function's context. If the caller is a
6655 ":ref:`call <i_call>`" instruction, execution continues at the
6656 instruction after the call. If the caller was an
6657 ":ref:`invoke <i_invoke>`" instruction, execution continues at the
6658 beginning of the "normal" destination block. If the instruction returns
6659 a value, that value shall set the call or invoke instruction's return
6665 .. code-block:: llvm
6667 ret i32 5 ; Return an integer value of 5
6668 ret void ; Return from a void function
6669 ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
6673 '``br``' Instruction
6674 ^^^^^^^^^^^^^^^^^^^^
6681 br i1 <cond>, label <iftrue>, label <iffalse>
6682 br label <dest> ; Unconditional branch
6687 The '``br``' instruction is used to cause control flow to transfer to a
6688 different basic block in the current function. There are two forms of
6689 this instruction, corresponding to a conditional branch and an
6690 unconditional branch.
6695 The conditional branch form of the '``br``' instruction takes a single
6696 '``i1``' value and two '``label``' values. The unconditional form of the
6697 '``br``' instruction takes a single '``label``' value as a target.
6702 Upon execution of a conditional '``br``' instruction, the '``i1``'
6703 argument is evaluated. If the value is ``true``, control flows to the
6704 '``iftrue``' ``label`` argument. If "cond" is ``false``, control flows
6705 to the '``iffalse``' ``label`` argument.
6710 .. code-block:: llvm
6713 %cond = icmp eq i32 %a, %b
6714 br i1 %cond, label %IfEqual, label %IfUnequal
6722 '``switch``' Instruction
6723 ^^^^^^^^^^^^^^^^^^^^^^^^
6730 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
6735 The '``switch``' instruction is used to transfer control flow to one of
6736 several different places. It is a generalization of the '``br``'
6737 instruction, allowing a branch to occur to one of many possible
6743 The '``switch``' instruction uses three parameters: an integer
6744 comparison value '``value``', a default '``label``' destination, and an
6745 array of pairs of comparison value constants and '``label``'s. The table
6746 is not allowed to contain duplicate constant entries.
6751 The ``switch`` instruction specifies a table of values and destinations.
6752 When the '``switch``' instruction is executed, this table is searched
6753 for the given value. If the value is found, control flow is transferred
6754 to the corresponding destination; otherwise, control flow is transferred
6755 to the default destination.
6760 Depending on properties of the target machine and the particular
6761 ``switch`` instruction, this instruction may be code generated in
6762 different ways. For example, it could be generated as a series of
6763 chained conditional branches or with a lookup table.
6768 .. code-block:: llvm
6770 ; Emulate a conditional br instruction
6771 %Val = zext i1 %value to i32
6772 switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
6774 ; Emulate an unconditional br instruction
6775 switch i32 0, label %dest [ ]
6777 ; Implement a jump table:
6778 switch i32 %val, label %otherwise [ i32 0, label %onzero
6780 i32 2, label %ontwo ]
6784 '``indirectbr``' Instruction
6785 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6792 indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
6797 The '``indirectbr``' instruction implements an indirect branch to a
6798 label within the current function, whose address is specified by
6799 "``address``". Address must be derived from a
6800 :ref:`blockaddress <blockaddress>` constant.
6805 The '``address``' argument is the address of the label to jump to. The
6806 rest of the arguments indicate the full set of possible destinations
6807 that the address may point to. Blocks are allowed to occur multiple
6808 times in the destination list, though this isn't particularly useful.
6810 This destination list is required so that dataflow analysis has an
6811 accurate understanding of the CFG.
6816 Control transfers to the block specified in the address argument. All
6817 possible destination blocks must be listed in the label list, otherwise
6818 this instruction has undefined behavior. This implies that jumps to
6819 labels defined in other functions have undefined behavior as well.
6824 This is typically implemented with a jump through a register.
6829 .. code-block:: llvm
6831 indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
6835 '``invoke``' Instruction
6836 ^^^^^^^^^^^^^^^^^^^^^^^^
6843 <result> = invoke [cconv] [ret attrs] [addrspace(<num>)] [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
6844 [operand bundles] to label <normal label> unwind label <exception label>
6849 The '``invoke``' instruction causes control to transfer to a specified
6850 function, with the possibility of control flow transfer to either the
6851 '``normal``' label or the '``exception``' label. If the callee function
6852 returns with the "``ret``" instruction, control flow will return to the
6853 "normal" label. If the callee (or any indirect callees) returns via the
6854 ":ref:`resume <i_resume>`" instruction or other exception handling
6855 mechanism, control is interrupted and continued at the dynamically
6856 nearest "exception" label.
6858 The '``exception``' label is a `landing
6859 pad <ExceptionHandling.html#overview>`_ for the exception. As such,
6860 '``exception``' label is required to have the
6861 ":ref:`landingpad <i_landingpad>`" instruction, which contains the
6862 information about the behavior of the program after unwinding happens,
6863 as its first non-PHI instruction. The restrictions on the
6864 "``landingpad``" instruction's tightly couples it to the "``invoke``"
6865 instruction, so that the important information contained within the
6866 "``landingpad``" instruction can't be lost through normal code motion.
6871 This instruction requires several arguments:
6873 #. The optional "cconv" marker indicates which :ref:`calling
6874 convention <callingconv>` the call should use. If none is
6875 specified, the call defaults to using C calling conventions.
6876 #. The optional :ref:`Parameter Attributes <paramattrs>` list for return
6877 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
6879 #. The optional addrspace attribute can be used to indicate the address space
6880 of the called function. If it is not specified, the program address space
6881 from the :ref:`datalayout string<langref_datalayout>` will be used.
6882 #. '``ty``': the type of the call instruction itself which is also the
6883 type of the return value. Functions that return no value are marked
6885 #. '``fnty``': shall be the signature of the function being invoked. The
6886 argument types must match the types implied by this signature. This
6887 type can be omitted if the function is not varargs.
6888 #. '``fnptrval``': An LLVM value containing a pointer to a function to
6889 be invoked. In most cases, this is a direct function invocation, but
6890 indirect ``invoke``'s are just as possible, calling an arbitrary pointer
6892 #. '``function args``': argument list whose types match the function
6893 signature argument types and parameter attributes. All arguments must
6894 be of :ref:`first class <t_firstclass>` type. If the function signature
6895 indicates the function accepts a variable number of arguments, the
6896 extra arguments can be specified.
6897 #. '``normal label``': the label reached when the called function
6898 executes a '``ret``' instruction.
6899 #. '``exception label``': the label reached when a callee returns via
6900 the :ref:`resume <i_resume>` instruction or other exception handling
6902 #. The optional :ref:`function attributes <fnattrs>` list.
6903 #. The optional :ref:`operand bundles <opbundles>` list.
6908 This instruction is designed to operate as a standard '``call``'
6909 instruction in most regards. The primary difference is that it
6910 establishes an association with a label, which is used by the runtime
6911 library to unwind the stack.
6913 This instruction is used in languages with destructors to ensure that
6914 proper cleanup is performed in the case of either a ``longjmp`` or a
6915 thrown exception. Additionally, this is important for implementation of
6916 '``catch``' clauses in high-level languages that support them.
6918 For the purposes of the SSA form, the definition of the value returned
6919 by the '``invoke``' instruction is deemed to occur on the edge from the
6920 current block to the "normal" label. If the callee unwinds then no
6921 return value is available.
6926 .. code-block:: llvm
6928 %retval = invoke i32 @Test(i32 15) to label %Continue
6929 unwind label %TestCleanup ; i32:retval set
6930 %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
6931 unwind label %TestCleanup ; i32:retval set
6935 '``callbr``' Instruction
6936 ^^^^^^^^^^^^^^^^^^^^^^^^
6943 <result> = callbr [cconv] [ret attrs] [addrspace(<num>)] [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
6944 [operand bundles] to label <normal label> or jump [other labels]
6949 The '``callbr``' instruction causes control to transfer to a specified
6950 function, with the possibility of control flow transfer to either the
6951 '``normal``' label or one of the '``other``' labels.
6953 This instruction should only be used to implement the "goto" feature of gcc
6954 style inline assembly. Any other usage is an error in the IR verifier.
6959 This instruction requires several arguments:
6961 #. The optional "cconv" marker indicates which :ref:`calling
6962 convention <callingconv>` the call should use. If none is
6963 specified, the call defaults to using C calling conventions.
6964 #. The optional :ref:`Parameter Attributes <paramattrs>` list for return
6965 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
6967 #. The optional addrspace attribute can be used to indicate the address space
6968 of the called function. If it is not specified, the program address space
6969 from the :ref:`datalayout string<langref_datalayout>` will be used.
6970 #. '``ty``': the type of the call instruction itself which is also the
6971 type of the return value. Functions that return no value are marked
6973 #. '``fnty``': shall be the signature of the function being called. The
6974 argument types must match the types implied by this signature. This
6975 type can be omitted if the function is not varargs.
6976 #. '``fnptrval``': An LLVM value containing a pointer to a function to
6977 be called. In most cases, this is a direct function call, but
6978 indirect ``callbr``'s are just as possible, calling an arbitrary pointer
6980 #. '``function args``': argument list whose types match the function
6981 signature argument types and parameter attributes. All arguments must
6982 be of :ref:`first class <t_firstclass>` type. If the function signature
6983 indicates the function accepts a variable number of arguments, the
6984 extra arguments can be specified.
6985 #. '``normal label``': the label reached when the called function
6986 executes a '``ret``' instruction.
6987 #. '``other labels``': the labels reached when a callee transfers control
6988 to a location other than the normal '``normal label``'
6989 #. The optional :ref:`function attributes <fnattrs>` list.
6990 #. The optional :ref:`operand bundles <opbundles>` list.
6995 This instruction is designed to operate as a standard '``call``'
6996 instruction in most regards. The primary difference is that it
6997 establishes an association with additional labels to define where control
6998 flow goes after the call.
7000 The only use of this today is to implement the "goto" feature of gcc inline
7001 assembly where additional labels can be provided as locations for the inline
7002 assembly to jump to.
7007 .. code-block:: text
7009 callbr void asm "", "r,x"(i32 %x, i8 *blockaddress(@foo, %fail))
7010 to label %normal or jump [label %fail]
7014 '``resume``' Instruction
7015 ^^^^^^^^^^^^^^^^^^^^^^^^
7022 resume <type> <value>
7027 The '``resume``' instruction is a terminator instruction that has no
7033 The '``resume``' instruction requires one argument, which must have the
7034 same type as the result of any '``landingpad``' instruction in the same
7040 The '``resume``' instruction resumes propagation of an existing
7041 (in-flight) exception whose unwinding was interrupted with a
7042 :ref:`landingpad <i_landingpad>` instruction.
7047 .. code-block:: llvm
7049 resume { i8*, i32 } %exn
7053 '``catchswitch``' Instruction
7054 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7061 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller
7062 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default>
7067 The '``catchswitch``' instruction is used by `LLVM's exception handling system
7068 <ExceptionHandling.html#overview>`_ to describe the set of possible catch handlers
7069 that may be executed by the :ref:`EH personality routine <personalityfn>`.
7074 The ``parent`` argument is the token of the funclet that contains the
7075 ``catchswitch`` instruction. If the ``catchswitch`` is not inside a funclet,
7076 this operand may be the token ``none``.
7078 The ``default`` argument is the label of another basic block beginning with
7079 either a ``cleanuppad`` or ``catchswitch`` instruction. This unwind destination
7080 must be a legal target with respect to the ``parent`` links, as described in
7081 the `exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_.
7083 The ``handlers`` are a nonempty list of successor blocks that each begin with a
7084 :ref:`catchpad <i_catchpad>` instruction.
7089 Executing this instruction transfers control to one of the successors in
7090 ``handlers``, if appropriate, or continues to unwind via the unwind label if
7093 The ``catchswitch`` is both a terminator and a "pad" instruction, meaning that
7094 it must be both the first non-phi instruction and last instruction in the basic
7095 block. Therefore, it must be the only non-phi instruction in the block.
7100 .. code-block:: text
7103 %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to caller
7105 %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup
7109 '``catchret``' Instruction
7110 ^^^^^^^^^^^^^^^^^^^^^^^^^^
7117 catchret from <token> to label <normal>
7122 The '``catchret``' instruction is a terminator instruction that has a
7129 The first argument to a '``catchret``' indicates which ``catchpad`` it
7130 exits. It must be a :ref:`catchpad <i_catchpad>`.
7131 The second argument to a '``catchret``' specifies where control will
7137 The '``catchret``' instruction ends an existing (in-flight) exception whose
7138 unwinding was interrupted with a :ref:`catchpad <i_catchpad>` instruction. The
7139 :ref:`personality function <personalityfn>` gets a chance to execute arbitrary
7140 code to, for example, destroy the active exception. Control then transfers to
7143 The ``token`` argument must be a token produced by a ``catchpad`` instruction.
7144 If the specified ``catchpad`` is not the most-recently-entered not-yet-exited
7145 funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_),
7146 the ``catchret``'s behavior is undefined.
7151 .. code-block:: text
7153 catchret from %catch label %continue
7157 '``cleanupret``' Instruction
7158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7165 cleanupret from <value> unwind label <continue>
7166 cleanupret from <value> unwind to caller
7171 The '``cleanupret``' instruction is a terminator instruction that has
7172 an optional successor.
7178 The '``cleanupret``' instruction requires one argument, which indicates
7179 which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_cleanuppad>`.
7180 If the specified ``cleanuppad`` is not the most-recently-entered not-yet-exited
7181 funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_),
7182 the ``cleanupret``'s behavior is undefined.
7184 The '``cleanupret``' instruction also has an optional successor, ``continue``,
7185 which must be the label of another basic block beginning with either a
7186 ``cleanuppad`` or ``catchswitch`` instruction. This unwind destination must
7187 be a legal target with respect to the ``parent`` links, as described in the
7188 `exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_.
7193 The '``cleanupret``' instruction indicates to the
7194 :ref:`personality function <personalityfn>` that one
7195 :ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended.
7196 It transfers control to ``continue`` or unwinds out of the function.
7201 .. code-block:: text
7203 cleanupret from %cleanup unwind to caller
7204 cleanupret from %cleanup unwind label %continue
7208 '``unreachable``' Instruction
7209 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7221 The '``unreachable``' instruction has no defined semantics. This
7222 instruction is used to inform the optimizer that a particular portion of
7223 the code is not reachable. This can be used to indicate that the code
7224 after a no-return function cannot be reached, and other facts.
7229 The '``unreachable``' instruction has no defined semantics.
7236 Unary operators require a single operand, execute an operation on
7237 it, and produce a single value. The operand might represent multiple
7238 data, as is the case with the :ref:`vector <t_vector>` data type. The
7239 result value has the same type as its operand.
7243 '``fneg``' Instruction
7244 ^^^^^^^^^^^^^^^^^^^^^^
7251 <result> = fneg [fast-math flags]* <ty> <op1> ; yields ty:result
7256 The '``fneg``' instruction returns the negation of its operand.
7261 The argument to the '``fneg``' instruction must be a
7262 :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
7263 floating-point values.
7268 The value produced is a copy of the operand with its sign bit flipped.
7269 This instruction can also take any number of :ref:`fast-math
7270 flags <fastmath>`, which are optimization hints to enable otherwise
7271 unsafe floating-point optimizations:
7276 .. code-block:: text
7278 <result> = fneg float %val ; yields float:result = -%var
7285 Binary operators are used to do most of the computation in a program.
7286 They require two operands of the same type, execute an operation on
7287 them, and produce a single value. The operands might represent multiple
7288 data, as is the case with the :ref:`vector <t_vector>` data type. The
7289 result value has the same type as its operands.
7291 There are several different binary operators:
7295 '``add``' Instruction
7296 ^^^^^^^^^^^^^^^^^^^^^
7303 <result> = add <ty> <op1>, <op2> ; yields ty:result
7304 <result> = add nuw <ty> <op1>, <op2> ; yields ty:result
7305 <result> = add nsw <ty> <op1>, <op2> ; yields ty:result
7306 <result> = add nuw nsw <ty> <op1>, <op2> ; yields ty:result
7311 The '``add``' instruction returns the sum of its two operands.
7316 The two arguments to the '``add``' instruction must be
7317 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
7318 arguments must have identical types.
7323 The value produced is the integer sum of the two operands.
7325 If the sum has unsigned overflow, the result returned is the
7326 mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
7329 Because LLVM integers use a two's complement representation, this
7330 instruction is appropriate for both signed and unsigned integers.
7332 ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
7333 respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
7334 result value of the ``add`` is a :ref:`poison value <poisonvalues>` if
7335 unsigned and/or signed overflow, respectively, occurs.
7340 .. code-block:: text
7342 <result> = add i32 4, %var ; yields i32:result = 4 + %var
7346 '``fadd``' Instruction
7347 ^^^^^^^^^^^^^^^^^^^^^^
7354 <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
7359 The '``fadd``' instruction returns the sum of its two operands.
7364 The two arguments to the '``fadd``' instruction must be
7365 :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
7366 floating-point values. Both arguments must have identical types.
7371 The value produced is the floating-point sum of the two operands.
7372 This instruction is assumed to execute in the default :ref:`floating-point
7373 environment <floatenv>`.
7374 This instruction can also take any number of :ref:`fast-math
7375 flags <fastmath>`, which are optimization hints to enable otherwise
7376 unsafe floating-point optimizations:
7381 .. code-block:: text
7383 <result> = fadd float 4.0, %var ; yields float:result = 4.0 + %var
7385 '``sub``' Instruction
7386 ^^^^^^^^^^^^^^^^^^^^^
7393 <result> = sub <ty> <op1>, <op2> ; yields ty:result
7394 <result> = sub nuw <ty> <op1>, <op2> ; yields ty:result
7395 <result> = sub nsw <ty> <op1>, <op2> ; yields ty:result
7396 <result> = sub nuw nsw <ty> <op1>, <op2> ; yields ty:result
7401 The '``sub``' instruction returns the difference of its two operands.
7403 Note that the '``sub``' instruction is used to represent the '``neg``'
7404 instruction present in most other intermediate representations.
7409 The two arguments to the '``sub``' instruction must be
7410 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
7411 arguments must have identical types.
7416 The value produced is the integer difference of the two operands.
7418 If the difference has unsigned overflow, the result returned is the
7419 mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
7422 Because LLVM integers use a two's complement representation, this
7423 instruction is appropriate for both signed and unsigned integers.
7425 ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
7426 respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
7427 result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if
7428 unsigned and/or signed overflow, respectively, occurs.
7433 .. code-block:: text
7435 <result> = sub i32 4, %var ; yields i32:result = 4 - %var
7436 <result> = sub i32 0, %val ; yields i32:result = -%var
7440 '``fsub``' Instruction
7441 ^^^^^^^^^^^^^^^^^^^^^^
7448 <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
7453 The '``fsub``' instruction returns the difference of its two operands.
7458 The two arguments to the '``fsub``' instruction must be
7459 :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
7460 floating-point values. Both arguments must have identical types.
7465 The value produced is the floating-point difference of the two operands.
7466 This instruction is assumed to execute in the default :ref:`floating-point
7467 environment <floatenv>`.
7468 This instruction can also take any number of :ref:`fast-math
7469 flags <fastmath>`, which are optimization hints to enable otherwise
7470 unsafe floating-point optimizations:
7475 .. code-block:: text
7477 <result> = fsub float 4.0, %var ; yields float:result = 4.0 - %var
7478 <result> = fsub float -0.0, %val ; yields float:result = -%var
7480 '``mul``' Instruction
7481 ^^^^^^^^^^^^^^^^^^^^^
7488 <result> = mul <ty> <op1>, <op2> ; yields ty:result
7489 <result> = mul nuw <ty> <op1>, <op2> ; yields ty:result
7490 <result> = mul nsw <ty> <op1>, <op2> ; yields ty:result
7491 <result> = mul nuw nsw <ty> <op1>, <op2> ; yields ty:result
7496 The '``mul``' instruction returns the product of its two operands.
7501 The two arguments to the '``mul``' instruction must be
7502 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
7503 arguments must have identical types.
7508 The value produced is the integer product of the two operands.
7510 If the result of the multiplication has unsigned overflow, the result
7511 returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the
7512 bit width of the result.
7514 Because LLVM integers use a two's complement representation, and the
7515 result is the same width as the operands, this instruction returns the
7516 correct result for both signed and unsigned integers. If a full product
7517 (e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be
7518 sign-extended or zero-extended as appropriate to the width of the full
7521 ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
7522 respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
7523 result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if
7524 unsigned and/or signed overflow, respectively, occurs.
7529 .. code-block:: text
7531 <result> = mul i32 4, %var ; yields i32:result = 4 * %var
7535 '``fmul``' Instruction
7536 ^^^^^^^^^^^^^^^^^^^^^^
7543 <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
7548 The '``fmul``' instruction returns the product of its two operands.
7553 The two arguments to the '``fmul``' instruction must be
7554 :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
7555 floating-point values. Both arguments must have identical types.
7560 The value produced is the floating-point product of the two operands.
7561 This instruction is assumed to execute in the default :ref:`floating-point
7562 environment <floatenv>`.
7563 This instruction can also take any number of :ref:`fast-math
7564 flags <fastmath>`, which are optimization hints to enable otherwise
7565 unsafe floating-point optimizations:
7570 .. code-block:: text
7572 <result> = fmul float 4.0, %var ; yields float:result = 4.0 * %var
7574 '``udiv``' Instruction
7575 ^^^^^^^^^^^^^^^^^^^^^^
7582 <result> = udiv <ty> <op1>, <op2> ; yields ty:result
7583 <result> = udiv exact <ty> <op1>, <op2> ; yields ty:result
7588 The '``udiv``' instruction returns the quotient of its two operands.
7593 The two arguments to the '``udiv``' instruction must be
7594 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
7595 arguments must have identical types.
7600 The value produced is the unsigned integer quotient of the two operands.
7602 Note that unsigned integer division and signed integer division are
7603 distinct operations; for signed integer division, use '``sdiv``'.
7605 Division by zero is undefined behavior. For vectors, if any element
7606 of the divisor is zero, the operation has undefined behavior.
7609 If the ``exact`` keyword is present, the result value of the ``udiv`` is
7610 a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as
7611 such, "((a udiv exact b) mul b) == a").
7616 .. code-block:: text
7618 <result> = udiv i32 4, %var ; yields i32:result = 4 / %var
7620 '``sdiv``' Instruction
7621 ^^^^^^^^^^^^^^^^^^^^^^
7628 <result> = sdiv <ty> <op1>, <op2> ; yields ty:result
7629 <result> = sdiv exact <ty> <op1>, <op2> ; yields ty:result
7634 The '``sdiv``' instruction returns the quotient of its two operands.
7639 The two arguments to the '``sdiv``' instruction must be
7640 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
7641 arguments must have identical types.
7646 The value produced is the signed integer quotient of the two operands
7647 rounded towards zero.
7649 Note that signed integer division and unsigned integer division are
7650 distinct operations; for unsigned integer division, use '``udiv``'.
7652 Division by zero is undefined behavior. For vectors, if any element
7653 of the divisor is zero, the operation has undefined behavior.
7654 Overflow also leads to undefined behavior; this is a rare case, but can
7655 occur, for example, by doing a 32-bit division of -2147483648 by -1.
7657 If the ``exact`` keyword is present, the result value of the ``sdiv`` is
7658 a :ref:`poison value <poisonvalues>` if the result would be rounded.
7663 .. code-block:: text
7665 <result> = sdiv i32 4, %var ; yields i32:result = 4 / %var
7669 '``fdiv``' Instruction
7670 ^^^^^^^^^^^^^^^^^^^^^^
7677 <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
7682 The '``fdiv``' instruction returns the quotient of its two operands.
7687 The two arguments to the '``fdiv``' instruction must be
7688 :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
7689 floating-point values. Both arguments must have identical types.
7694 The value produced is the floating-point quotient of the two operands.
7695 This instruction is assumed to execute in the default :ref:`floating-point
7696 environment <floatenv>`.
7697 This instruction can also take any number of :ref:`fast-math
7698 flags <fastmath>`, which are optimization hints to enable otherwise
7699 unsafe floating-point optimizations:
7704 .. code-block:: text
7706 <result> = fdiv float 4.0, %var ; yields float:result = 4.0 / %var
7708 '``urem``' Instruction
7709 ^^^^^^^^^^^^^^^^^^^^^^
7716 <result> = urem <ty> <op1>, <op2> ; yields ty:result
7721 The '``urem``' instruction returns the remainder from the unsigned
7722 division of its two arguments.
7727 The two arguments to the '``urem``' instruction must be
7728 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
7729 arguments must have identical types.
7734 This instruction returns the unsigned integer *remainder* of a division.
7735 This instruction always performs an unsigned division to get the
7738 Note that unsigned integer remainder and signed integer remainder are
7739 distinct operations; for signed integer remainder, use '``srem``'.
7741 Taking the remainder of a division by zero is undefined behavior.
7742 For vectors, if any element of the divisor is zero, the operation has
7748 .. code-block:: text
7750 <result> = urem i32 4, %var ; yields i32:result = 4 % %var
7752 '``srem``' Instruction
7753 ^^^^^^^^^^^^^^^^^^^^^^
7760 <result> = srem <ty> <op1>, <op2> ; yields ty:result
7765 The '``srem``' instruction returns the remainder from the signed
7766 division of its two operands. This instruction can also take
7767 :ref:`vector <t_vector>` versions of the values in which case the elements
7773 The two arguments to the '``srem``' instruction must be
7774 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
7775 arguments must have identical types.
7780 This instruction returns the *remainder* of a division (where the result
7781 is either zero or has the same sign as the dividend, ``op1``), not the
7782 *modulo* operator (where the result is either zero or has the same sign
7783 as the divisor, ``op2``) of a value. For more information about the
7784 difference, see `The Math
7785 Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a
7786 table of how this is implemented in various languages, please see
7788 operation <http://en.wikipedia.org/wiki/Modulo_operation>`_.
7790 Note that signed integer remainder and unsigned integer remainder are
7791 distinct operations; for unsigned integer remainder, use '``urem``'.
7793 Taking the remainder of a division by zero is undefined behavior.
7794 For vectors, if any element of the divisor is zero, the operation has
7796 Overflow also leads to undefined behavior; this is a rare case, but can
7797 occur, for example, by taking the remainder of a 32-bit division of
7798 -2147483648 by -1. (The remainder doesn't actually overflow, but this
7799 rule lets srem be implemented using instructions that return both the
7800 result of the division and the remainder.)
7805 .. code-block:: text
7807 <result> = srem i32 4, %var ; yields i32:result = 4 % %var
7811 '``frem``' Instruction
7812 ^^^^^^^^^^^^^^^^^^^^^^
7819 <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
7824 The '``frem``' instruction returns the remainder from the division of
7830 The two arguments to the '``frem``' instruction must be
7831 :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
7832 floating-point values. Both arguments must have identical types.
7837 The value produced is the floating-point remainder of the two operands.
7838 This is the same output as a libm '``fmod``' function, but without any
7839 possibility of setting ``errno``. The remainder has the same sign as the
7841 This instruction is assumed to execute in the default :ref:`floating-point
7842 environment <floatenv>`.
7843 This instruction can also take any number of :ref:`fast-math
7844 flags <fastmath>`, which are optimization hints to enable otherwise
7845 unsafe floating-point optimizations:
7850 .. code-block:: text
7852 <result> = frem float 4.0, %var ; yields float:result = 4.0 % %var
7856 Bitwise Binary Operations
7857 -------------------------
7859 Bitwise binary operators are used to do various forms of bit-twiddling
7860 in a program. They are generally very efficient instructions and can
7861 commonly be strength reduced from other instructions. They require two
7862 operands of the same type, execute an operation on them, and produce a
7863 single value. The resulting value is the same type as its operands.
7865 '``shl``' Instruction
7866 ^^^^^^^^^^^^^^^^^^^^^
7873 <result> = shl <ty> <op1>, <op2> ; yields ty:result
7874 <result> = shl nuw <ty> <op1>, <op2> ; yields ty:result
7875 <result> = shl nsw <ty> <op1>, <op2> ; yields ty:result
7876 <result> = shl nuw nsw <ty> <op1>, <op2> ; yields ty:result
7881 The '``shl``' instruction returns the first operand shifted to the left
7882 a specified number of bits.
7887 Both arguments to the '``shl``' instruction must be the same
7888 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
7889 '``op2``' is treated as an unsigned value.
7894 The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`,
7895 where ``n`` is the width of the result. If ``op2`` is (statically or
7896 dynamically) equal to or larger than the number of bits in
7897 ``op1``, this instruction returns a :ref:`poison value <poisonvalues>`.
7898 If the arguments are vectors, each vector element of ``op1`` is shifted
7899 by the corresponding shift amount in ``op2``.
7901 If the ``nuw`` keyword is present, then the shift produces a poison
7902 value if it shifts out any non-zero bits.
7903 If the ``nsw`` keyword is present, then the shift produces a poison
7904 value if it shifts out any bits that disagree with the resultant sign bit.
7909 .. code-block:: text
7911 <result> = shl i32 4, %var ; yields i32: 4 << %var
7912 <result> = shl i32 4, 2 ; yields i32: 16
7913 <result> = shl i32 1, 10 ; yields i32: 1024
7914 <result> = shl i32 1, 32 ; undefined
7915 <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4>
7917 '``lshr``' Instruction
7918 ^^^^^^^^^^^^^^^^^^^^^^
7925 <result> = lshr <ty> <op1>, <op2> ; yields ty:result
7926 <result> = lshr exact <ty> <op1>, <op2> ; yields ty:result
7931 The '``lshr``' instruction (logical shift right) returns the first
7932 operand shifted to the right a specified number of bits with zero fill.
7937 Both arguments to the '``lshr``' instruction must be the same
7938 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
7939 '``op2``' is treated as an unsigned value.
7944 This instruction always performs a logical shift right operation. The
7945 most significant bits of the result will be filled with zero bits after
7946 the shift. If ``op2`` is (statically or dynamically) equal to or larger
7947 than the number of bits in ``op1``, this instruction returns a :ref:`poison
7948 value <poisonvalues>`. If the arguments are vectors, each vector element
7949 of ``op1`` is shifted by the corresponding shift amount in ``op2``.
7951 If the ``exact`` keyword is present, the result value of the ``lshr`` is
7952 a poison value if any of the bits shifted out are non-zero.
7957 .. code-block:: text
7959 <result> = lshr i32 4, 1 ; yields i32:result = 2
7960 <result> = lshr i32 4, 2 ; yields i32:result = 1
7961 <result> = lshr i8 4, 3 ; yields i8:result = 0
7962 <result> = lshr i8 -2, 1 ; yields i8:result = 0x7F
7963 <result> = lshr i32 1, 32 ; undefined
7964 <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
7966 '``ashr``' Instruction
7967 ^^^^^^^^^^^^^^^^^^^^^^
7974 <result> = ashr <ty> <op1>, <op2> ; yields ty:result
7975 <result> = ashr exact <ty> <op1>, <op2> ; yields ty:result
7980 The '``ashr``' instruction (arithmetic shift right) returns the first
7981 operand shifted to the right a specified number of bits with sign
7987 Both arguments to the '``ashr``' instruction must be the same
7988 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
7989 '``op2``' is treated as an unsigned value.
7994 This instruction always performs an arithmetic shift right operation,
7995 The most significant bits of the result will be filled with the sign bit
7996 of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger
7997 than the number of bits in ``op1``, this instruction returns a :ref:`poison
7998 value <poisonvalues>`. If the arguments are vectors, each vector element
7999 of ``op1`` is shifted by the corresponding shift amount in ``op2``.
8001 If the ``exact`` keyword is present, the result value of the ``ashr`` is
8002 a poison value if any of the bits shifted out are non-zero.
8007 .. code-block:: text
8009 <result> = ashr i32 4, 1 ; yields i32:result = 2
8010 <result> = ashr i32 4, 2 ; yields i32:result = 1
8011 <result> = ashr i8 4, 3 ; yields i8:result = 0
8012 <result> = ashr i8 -2, 1 ; yields i8:result = -1
8013 <result> = ashr i32 1, 32 ; undefined
8014 <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0>
8016 '``and``' Instruction
8017 ^^^^^^^^^^^^^^^^^^^^^
8024 <result> = and <ty> <op1>, <op2> ; yields ty:result
8029 The '``and``' instruction returns the bitwise logical and of its two
8035 The two arguments to the '``and``' instruction must be
8036 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
8037 arguments must have identical types.
8042 The truth table used for the '``and``' instruction is:
8059 .. code-block:: text
8061 <result> = and i32 4, %var ; yields i32:result = 4 & %var
8062 <result> = and i32 15, 40 ; yields i32:result = 8
8063 <result> = and i32 4, 8 ; yields i32:result = 0
8065 '``or``' Instruction
8066 ^^^^^^^^^^^^^^^^^^^^
8073 <result> = or <ty> <op1>, <op2> ; yields ty:result
8078 The '``or``' instruction returns the bitwise logical inclusive or of its
8084 The two arguments to the '``or``' instruction must be
8085 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
8086 arguments must have identical types.
8091 The truth table used for the '``or``' instruction is:
8110 <result> = or i32 4, %var ; yields i32:result = 4 | %var
8111 <result> = or i32 15, 40 ; yields i32:result = 47
8112 <result> = or i32 4, 8 ; yields i32:result = 12
8114 '``xor``' Instruction
8115 ^^^^^^^^^^^^^^^^^^^^^
8122 <result> = xor <ty> <op1>, <op2> ; yields ty:result
8127 The '``xor``' instruction returns the bitwise logical exclusive or of
8128 its two operands. The ``xor`` is used to implement the "one's
8129 complement" operation, which is the "~" operator in C.
8134 The two arguments to the '``xor``' instruction must be
8135 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
8136 arguments must have identical types.
8141 The truth table used for the '``xor``' instruction is:
8158 .. code-block:: text
8160 <result> = xor i32 4, %var ; yields i32:result = 4 ^ %var
8161 <result> = xor i32 15, 40 ; yields i32:result = 39
8162 <result> = xor i32 4, 8 ; yields i32:result = 12
8163 <result> = xor i32 %V, -1 ; yields i32:result = ~%V
8168 LLVM supports several instructions to represent vector operations in a
8169 target-independent manner. These instructions cover the element-access
8170 and vector-specific operations needed to process vectors effectively.
8171 While LLVM does directly support these vector operations, many
8172 sophisticated algorithms will want to use target-specific intrinsics to
8173 take full advantage of a specific target.
8175 .. _i_extractelement:
8177 '``extractelement``' Instruction
8178 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8185 <result> = extractelement <n x <ty>> <val>, <ty2> <idx> ; yields <ty>
8186 <result> = extractelement <vscale x n x <ty>> <val>, <ty2> <idx> ; yields <ty>
8191 The '``extractelement``' instruction extracts a single scalar element
8192 from a vector at a specified index.
8197 The first operand of an '``extractelement``' instruction is a value of
8198 :ref:`vector <t_vector>` type. The second operand is an index indicating
8199 the position from which to extract the element. The index may be a
8200 variable of any integer type.
8205 The result is a scalar of the same type as the element type of ``val``.
8206 Its value is the value at position ``idx`` of ``val``. If ``idx``
8207 exceeds the length of ``val`` for a fixed-length vector, the result is a
8208 :ref:`poison value <poisonvalues>`. For a scalable vector, if the value
8209 of ``idx`` exceeds the runtime length of the vector, the result is a
8210 :ref:`poison value <poisonvalues>`.
8215 .. code-block:: text
8217 <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32
8219 .. _i_insertelement:
8221 '``insertelement``' Instruction
8222 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8229 <result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <n x <ty>>
8230 <result> = insertelement <vscale x n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <vscale x n x <ty>>
8235 The '``insertelement``' instruction inserts a scalar element into a
8236 vector at a specified index.
8241 The first operand of an '``insertelement``' instruction is a value of
8242 :ref:`vector <t_vector>` type. The second operand is a scalar value whose
8243 type must equal the element type of the first operand. The third operand
8244 is an index indicating the position at which to insert the value. The
8245 index may be a variable of any integer type.
8250 The result is a vector of the same type as ``val``. Its element values
8251 are those of ``val`` except at position ``idx``, where it gets the value
8252 ``elt``. If ``idx`` exceeds the length of ``val`` for a fixed-length vector,
8253 the result is a :ref:`poison value <poisonvalues>`. For a scalable vector,
8254 if the value of ``idx`` exceeds the runtime length of the vector, the result
8255 is a :ref:`poison value <poisonvalues>`.
8260 .. code-block:: text
8262 <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32>
8264 .. _i_shufflevector:
8266 '``shufflevector``' Instruction
8267 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8274 <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>>
8275 <result> = shufflevector <vscale x n x <ty>> <v1>, <vscale x n x <ty>> v2, <vscale x m x i32> <mask> ; yields <vscale x m x <ty>>
8280 The '``shufflevector``' instruction constructs a permutation of elements
8281 from two input vectors, returning a vector with the same element type as
8282 the input and length that is the same as the shuffle mask.
8287 The first two operands of a '``shufflevector``' instruction are vectors
8288 with the same type. The third argument is a shuffle mask whose element
8289 type is always 'i32'. The result of the instruction is a vector whose
8290 length is the same as the shuffle mask and whose element type is the
8291 same as the element type of the first two operands.
8293 The shuffle mask operand is required to be a constant vector with either
8294 constant integer or undef values.
8299 The elements of the two input vectors are numbered from left to right
8300 across both of the vectors. The shuffle mask operand specifies, for each
8301 element of the result vector, which element of the two input vectors the
8302 result element gets. If the shuffle mask is undef, the result vector is
8303 undef. If any element of the mask operand is undef, that element of the
8304 result is undef. If the shuffle mask selects an undef element from one
8305 of the input vectors, the resulting element is undef.
8307 For scalable vectors, the only valid mask values at present are
8308 ``zeroinitializer`` and ``undef``, since we cannot write all indices as
8309 literals for a vector with a length unknown at compile time.
8314 .. code-block:: text
8316 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
8317 <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32>
8318 <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
8319 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle.
8320 <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
8321 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32>
8322 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
8323 <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32>
8325 Aggregate Operations
8326 --------------------
8328 LLVM supports several instructions for working with
8329 :ref:`aggregate <t_aggregate>` values.
8333 '``extractvalue``' Instruction
8334 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8341 <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
8346 The '``extractvalue``' instruction extracts the value of a member field
8347 from an :ref:`aggregate <t_aggregate>` value.
8352 The first operand of an '``extractvalue``' instruction is a value of
8353 :ref:`struct <t_struct>` or :ref:`array <t_array>` type. The other operands are
8354 constant indices to specify which value to extract in a similar manner
8355 as indices in a '``getelementptr``' instruction.
8357 The major differences to ``getelementptr`` indexing are:
8359 - Since the value being indexed is not a pointer, the first index is
8360 omitted and assumed to be zero.
8361 - At least one index must be specified.
8362 - Not only struct indices but also array indices must be in bounds.
8367 The result is the value at the position in the aggregate specified by
8373 .. code-block:: text
8375 <result> = extractvalue {i32, float} %agg, 0 ; yields i32
8379 '``insertvalue``' Instruction
8380 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8387 <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type>
8392 The '``insertvalue``' instruction inserts a value into a member field in
8393 an :ref:`aggregate <t_aggregate>` value.
8398 The first operand of an '``insertvalue``' instruction is a value of
8399 :ref:`struct <t_struct>` or :ref:`array <t_array>` type. The second operand is
8400 a first-class value to insert. The following operands are constant
8401 indices indicating the position at which to insert the value in a
8402 similar manner as indices in a '``extractvalue``' instruction. The value
8403 to insert must have the same type as the value identified by the
8409 The result is an aggregate of the same type as ``val``. Its value is
8410 that of ``val`` except that the value at the position specified by the
8411 indices is that of ``elt``.
8416 .. code-block:: llvm
8418 %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef}
8419 %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val}
8420 %agg3 = insertvalue {i32, {float}} undef, float %val, 1, 0 ; yields {i32 undef, {float %val}}
8424 Memory Access and Addressing Operations
8425 ---------------------------------------
8427 A key design point of an SSA-based representation is how it represents
8428 memory. In LLVM, no memory locations are in SSA form, which makes things
8429 very simple. This section describes how to read, write, and allocate
8434 '``alloca``' Instruction
8435 ^^^^^^^^^^^^^^^^^^^^^^^^
8442 <result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] [, addrspace(<num>)] ; yields type addrspace(num)*:result
8447 The '``alloca``' instruction allocates memory on the stack frame of the
8448 currently executing function, to be automatically released when this
8449 function returns to its caller. The object is always allocated in the
8450 address space for allocas indicated in the datalayout.
8455 The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements``
8456 bytes of memory on the runtime stack, returning a pointer of the
8457 appropriate type to the program. If "NumElements" is specified, it is
8458 the number of elements allocated, otherwise "NumElements" is defaulted
8459 to be one. If a constant alignment is specified, the value result of the
8460 allocation is guaranteed to be aligned to at least that boundary. The
8461 alignment may not be greater than ``1 << 29``. If not specified, or if
8462 zero, the target can choose to align the allocation on any convenient
8463 boundary compatible with the type.
8465 '``type``' may be any sized type.
8470 Memory is allocated; a pointer is returned. The allocated memory is
8471 uninitialized, and loading from uninitialized memory produces an undefined
8472 value. The operation itself is undefined if there is insufficient stack
8473 space for the allocation.'``alloca``'d memory is automatically released
8474 when the function returns. The '``alloca``' instruction is commonly used
8475 to represent automatic variables that must have an address available. When
8476 the function returns (either with the ``ret`` or ``resume`` instructions),
8477 the memory is reclaimed. Allocating zero bytes is legal, but the returned
8478 pointer may not be unique. The order in which memory is allocated (ie.,
8479 which way the stack grows) is not specified.
8484 .. code-block:: llvm
8486 %ptr = alloca i32 ; yields i32*:ptr
8487 %ptr = alloca i32, i32 4 ; yields i32*:ptr
8488 %ptr = alloca i32, i32 4, align 1024 ; yields i32*:ptr
8489 %ptr = alloca i32, align 1024 ; yields i32*:ptr
8493 '``load``' Instruction
8494 ^^^^^^^^^^^^^^^^^^^^^^
8501 <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !invariant.group !<index>][, !nonnull !<index>][, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !align !<align_node>]
8502 <result> = load atomic [volatile] <ty>, <ty>* <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<index>]
8503 !<index> = !{ i32 1 }
8504 !<deref_bytes_node> = !{i64 <dereferenceable_bytes>}
8505 !<align_node> = !{ i64 <value_alignment> }
8510 The '``load``' instruction is used to read from memory.
8515 The argument to the ``load`` instruction specifies the memory address from which
8516 to load. The type specified must be a :ref:`first class <t_firstclass>` type of
8517 known size (i.e. not containing an :ref:`opaque structural type <t_opaque>`). If
8518 the ``load`` is marked as ``volatile``, then the optimizer is not allowed to
8519 modify the number or order of execution of this ``load`` with other
8520 :ref:`volatile operations <volatile>`.
8522 If the ``load`` is marked as ``atomic``, it takes an extra :ref:`ordering
8523 <ordering>` and optional ``syncscope("<target-scope>")`` argument. The
8524 ``release`` and ``acq_rel`` orderings are not valid on ``load`` instructions.
8525 Atomic loads produce :ref:`defined <memmodel>` results when they may see
8526 multiple atomic stores. The type of the pointee must be an integer, pointer, or
8527 floating-point type whose bit width is a power of two greater than or equal to
8528 eight and less than or equal to a target-specific size limit. ``align`` must be
8529 explicitly specified on atomic loads, and the load has undefined behavior if the
8530 alignment is not set to a value which is at least the size in bytes of the
8531 pointee. ``!nontemporal`` does not have any defined semantics for atomic loads.
8533 The optional constant ``align`` argument specifies the alignment of the
8534 operation (that is, the alignment of the memory address). A value of 0
8535 or an omitted ``align`` argument means that the operation has the ABI
8536 alignment for the target. It is the responsibility of the code emitter
8537 to ensure that the alignment information is correct. Overestimating the
8538 alignment results in undefined behavior. Underestimating the alignment
8539 may produce less efficient code. An alignment of 1 is always safe. The
8540 maximum possible alignment is ``1 << 29``. An alignment value higher
8541 than the size of the loaded type implies memory up to the alignment
8542 value bytes can be safely loaded without trapping in the default
8543 address space. Access of the high bytes can interfere with debugging
8544 tools, so should not be accessed if the function has the
8545 ``sanitize_thread`` or ``sanitize_address`` attributes.
8547 The optional ``!nontemporal`` metadata must reference a single
8548 metadata name ``<index>`` corresponding to a metadata node with one
8549 ``i32`` entry of value 1. The existence of the ``!nontemporal``
8550 metadata on the instruction tells the optimizer and code generator
8551 that this load is not expected to be reused in the cache. The code
8552 generator may select special instructions to save cache bandwidth, such
8553 as the ``MOVNT`` instruction on x86.
8555 The optional ``!invariant.load`` metadata must reference a single
8556 metadata name ``<index>`` corresponding to a metadata node with no
8557 entries. If a load instruction tagged with the ``!invariant.load``
8558 metadata is executed, the optimizer may assume the memory location
8559 referenced by the load contains the same value at all points in the
8560 program where the memory location is known to be dereferenceable;
8561 otherwise, the behavior is undefined.
8563 The optional ``!invariant.group`` metadata must reference a single metadata name
8564 ``<index>`` corresponding to a metadata node with no entries.
8565 See ``invariant.group`` metadata.
8567 The optional ``!nonnull`` metadata must reference a single
8568 metadata name ``<index>`` corresponding to a metadata node with no
8569 entries. The existence of the ``!nonnull`` metadata on the
8570 instruction tells the optimizer that the value loaded is known to
8571 never be null. If the value is null at runtime, the behavior is undefined.
8572 This is analogous to the ``nonnull`` attribute on parameters and return
8573 values. This metadata can only be applied to loads of a pointer type.
8575 The optional ``!dereferenceable`` metadata must reference a single metadata
8576 name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64``
8577 entry. The existence of the ``!dereferenceable`` metadata on the instruction
8578 tells the optimizer that the value loaded is known to be dereferenceable.
8579 The number of bytes known to be dereferenceable is specified by the integer
8580 value in the metadata node. This is analogous to the ''dereferenceable''
8581 attribute on parameters and return values. This metadata can only be applied
8582 to loads of a pointer type.
8584 The optional ``!dereferenceable_or_null`` metadata must reference a single
8585 metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one
8586 ``i64`` entry. The existence of the ``!dereferenceable_or_null`` metadata on the
8587 instruction tells the optimizer that the value loaded is known to be either
8588 dereferenceable or null.
8589 The number of bytes known to be dereferenceable is specified by the integer
8590 value in the metadata node. This is analogous to the ''dereferenceable_or_null''
8591 attribute on parameters and return values. This metadata can only be applied
8592 to loads of a pointer type.
8594 The optional ``!align`` metadata must reference a single metadata name
8595 ``<align_node>`` corresponding to a metadata node with one ``i64`` entry.
8596 The existence of the ``!align`` metadata on the instruction tells the
8597 optimizer that the value loaded is known to be aligned to a boundary specified
8598 by the integer value in the metadata node. The alignment must be a power of 2.
8599 This is analogous to the ''align'' attribute on parameters and return values.
8600 This metadata can only be applied to loads of a pointer type. If the returned
8601 value is not appropriately aligned at runtime, the behavior is undefined.
8606 The location of memory pointed to is loaded. If the value being loaded
8607 is of scalar type then the number of bytes read does not exceed the
8608 minimum number of bytes needed to hold all bits of the type. For
8609 example, loading an ``i24`` reads at most three bytes. When loading a
8610 value of a type like ``i20`` with a size that is not an integral number
8611 of bytes, the result is undefined if the value was not originally
8612 written using a store of the same type.
8617 .. code-block:: llvm
8619 %ptr = alloca i32 ; yields i32*:ptr
8620 store i32 3, i32* %ptr ; yields void
8621 %val = load i32, i32* %ptr ; yields i32:val = i32 3
8625 '``store``' Instruction
8626 ^^^^^^^^^^^^^^^^^^^^^^^
8633 store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.group !<index>] ; yields void
8634 store atomic [volatile] <ty> <value>, <ty>* <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<index>] ; yields void
8639 The '``store``' instruction is used to write to memory.
8644 There are two arguments to the ``store`` instruction: a value to store and an
8645 address at which to store it. The type of the ``<pointer>`` operand must be a
8646 pointer to the :ref:`first class <t_firstclass>` type of the ``<value>``
8647 operand. If the ``store`` is marked as ``volatile``, then the optimizer is not
8648 allowed to modify the number or order of execution of this ``store`` with other
8649 :ref:`volatile operations <volatile>`. Only values of :ref:`first class
8650 <t_firstclass>` types of known size (i.e. not containing an :ref:`opaque
8651 structural type <t_opaque>`) can be stored.
8653 If the ``store`` is marked as ``atomic``, it takes an extra :ref:`ordering
8654 <ordering>` and optional ``syncscope("<target-scope>")`` argument. The
8655 ``acquire`` and ``acq_rel`` orderings aren't valid on ``store`` instructions.
8656 Atomic loads produce :ref:`defined <memmodel>` results when they may see
8657 multiple atomic stores. The type of the pointee must be an integer, pointer, or
8658 floating-point type whose bit width is a power of two greater than or equal to
8659 eight and less than or equal to a target-specific size limit. ``align`` must be
8660 explicitly specified on atomic stores, and the store has undefined behavior if
8661 the alignment is not set to a value which is at least the size in bytes of the
8662 pointee. ``!nontemporal`` does not have any defined semantics for atomic stores.
8664 The optional constant ``align`` argument specifies the alignment of the
8665 operation (that is, the alignment of the memory address). A value of 0
8666 or an omitted ``align`` argument means that the operation has the ABI
8667 alignment for the target. It is the responsibility of the code emitter
8668 to ensure that the alignment information is correct. Overestimating the
8669 alignment results in undefined behavior. Underestimating the
8670 alignment may produce less efficient code. An alignment of 1 is always
8671 safe. The maximum possible alignment is ``1 << 29``. An alignment
8672 value higher than the size of the stored type implies memory up to the
8673 alignment value bytes can be stored to without trapping in the default
8674 address space. Storing to the higher bytes however may result in data
8675 races if another thread can access the same address. Introducing a
8676 data race is not allowed. Storing to the extra bytes is not allowed
8677 even in situations where a data race is known to not exist if the
8678 function has the ``sanitize_address`` attribute.
8680 The optional ``!nontemporal`` metadata must reference a single metadata
8681 name ``<index>`` corresponding to a metadata node with one ``i32`` entry of
8682 value 1. The existence of the ``!nontemporal`` metadata on the instruction
8683 tells the optimizer and code generator that this load is not expected to
8684 be reused in the cache. The code generator may select special
8685 instructions to save cache bandwidth, such as the ``MOVNT`` instruction on
8688 The optional ``!invariant.group`` metadata must reference a
8689 single metadata name ``<index>``. See ``invariant.group`` metadata.
8694 The contents of memory are updated to contain ``<value>`` at the
8695 location specified by the ``<pointer>`` operand. If ``<value>`` is
8696 of scalar type then the number of bytes written does not exceed the
8697 minimum number of bytes needed to hold all bits of the type. For
8698 example, storing an ``i24`` writes at most three bytes. When writing a
8699 value of a type like ``i20`` with a size that is not an integral number
8700 of bytes, it is unspecified what happens to the extra bits that do not
8701 belong to the type, but they will typically be overwritten.
8706 .. code-block:: llvm
8708 %ptr = alloca i32 ; yields i32*:ptr
8709 store i32 3, i32* %ptr ; yields void
8710 %val = load i32, i32* %ptr ; yields i32:val = i32 3
8714 '``fence``' Instruction
8715 ^^^^^^^^^^^^^^^^^^^^^^^
8722 fence [syncscope("<target-scope>")] <ordering> ; yields void
8727 The '``fence``' instruction is used to introduce happens-before edges
8733 '``fence``' instructions take an :ref:`ordering <ordering>` argument which
8734 defines what *synchronizes-with* edges they add. They can only be given
8735 ``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings.
8740 A fence A which has (at least) ``release`` ordering semantics
8741 *synchronizes with* a fence B with (at least) ``acquire`` ordering
8742 semantics if and only if there exist atomic operations X and Y, both
8743 operating on some atomic object M, such that A is sequenced before X, X
8744 modifies M (either directly or through some side effect of a sequence
8745 headed by X), Y is sequenced before B, and Y observes M. This provides a
8746 *happens-before* dependency between A and B. Rather than an explicit
8747 ``fence``, one (but not both) of the atomic operations X or Y might
8748 provide a ``release`` or ``acquire`` (resp.) ordering constraint and
8749 still *synchronize-with* the explicit ``fence`` and establish the
8750 *happens-before* edge.
8752 A ``fence`` which has ``seq_cst`` ordering, in addition to having both
8753 ``acquire`` and ``release`` semantics specified above, participates in
8754 the global program order of other ``seq_cst`` operations and/or fences.
8756 A ``fence`` instruction can also take an optional
8757 ":ref:`syncscope <syncscope>`" argument.
8762 .. code-block:: text
8764 fence acquire ; yields void
8765 fence syncscope("singlethread") seq_cst ; yields void
8766 fence syncscope("agent") seq_cst ; yields void
8770 '``cmpxchg``' Instruction
8771 ^^^^^^^^^^^^^^^^^^^^^^^^^
8778 cmpxchg [weak] [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [syncscope("<target-scope>")] <success ordering> <failure ordering> ; yields { ty, i1 }
8783 The '``cmpxchg``' instruction is used to atomically modify memory. It
8784 loads a value in memory and compares it to a given value. If they are
8785 equal, it tries to store a new value into the memory.
8790 There are three arguments to the '``cmpxchg``' instruction: an address
8791 to operate on, a value to compare to the value currently be at that
8792 address, and a new value to place at that address if the compared values
8793 are equal. The type of '<cmp>' must be an integer or pointer type whose
8794 bit width is a power of two greater than or equal to eight and less
8795 than or equal to a target-specific size limit. '<cmp>' and '<new>' must
8796 have the same type, and the type of '<pointer>' must be a pointer to
8797 that type. If the ``cmpxchg`` is marked as ``volatile``, then the
8798 optimizer is not allowed to modify the number or order of execution of
8799 this ``cmpxchg`` with other :ref:`volatile operations <volatile>`.
8801 The success and failure :ref:`ordering <ordering>` arguments specify how this
8802 ``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters
8803 must be at least ``monotonic``, the ordering constraint on failure must be no
8804 stronger than that on success, and the failure ordering cannot be either
8805 ``release`` or ``acq_rel``.
8807 A ``cmpxchg`` instruction can also take an optional
8808 ":ref:`syncscope <syncscope>`" argument.
8810 The pointer passed into cmpxchg must have alignment greater than or
8811 equal to the size in memory of the operand.
8816 The contents of memory at the location specified by the '``<pointer>``' operand
8817 is read and compared to '``<cmp>``'; if the values are equal, '``<new>``' is
8818 written to the location. The original value at the location is returned,
8819 together with a flag indicating success (true) or failure (false).
8821 If the cmpxchg operation is marked as ``weak`` then a spurious failure is
8822 permitted: the operation may not write ``<new>`` even if the comparison
8825 If the cmpxchg operation is strong (the default), the i1 value is 1 if and only
8826 if the value loaded equals ``cmp``.
8828 A successful ``cmpxchg`` is a read-modify-write instruction for the purpose of
8829 identifying release sequences. A failed ``cmpxchg`` is equivalent to an atomic
8830 load with an ordering parameter determined the second ordering parameter.
8835 .. code-block:: llvm
8838 %orig = load atomic i32, i32* %ptr unordered, align 4 ; yields i32
8842 %cmp = phi i32 [ %orig, %entry ], [%value_loaded, %loop]
8843 %squared = mul i32 %cmp, %cmp
8844 %val_success = cmpxchg i32* %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields { i32, i1 }
8845 %value_loaded = extractvalue { i32, i1 } %val_success, 0
8846 %success = extractvalue { i32, i1 } %val_success, 1
8847 br i1 %success, label %done, label %loop
8854 '``atomicrmw``' Instruction
8855 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
8862 atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [syncscope("<target-scope>")] <ordering> ; yields ty
8867 The '``atomicrmw``' instruction is used to atomically modify memory.
8872 There are three arguments to the '``atomicrmw``' instruction: an
8873 operation to apply, an address whose value to modify, an argument to the
8874 operation. The operation must be one of the following keywords:
8890 For most of these operations, the type of '<value>' must be an integer
8891 type whose bit width is a power of two greater than or equal to eight
8892 and less than or equal to a target-specific size limit. For xchg, this
8893 may also be a floating point type with the same size constraints as
8894 integers. For fadd/fsub, this must be a floating point type. The
8895 type of the '``<pointer>``' operand must be a pointer to that type. If
8896 the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not
8897 allowed to modify the number or order of execution of this
8898 ``atomicrmw`` with other :ref:`volatile operations <volatile>`.
8900 A ``atomicrmw`` instruction can also take an optional
8901 ":ref:`syncscope <syncscope>`" argument.
8906 The contents of memory at the location specified by the '``<pointer>``'
8907 operand are atomically read, modified, and written back. The original
8908 value at the location is returned. The modification is specified by the
8911 - xchg: ``*ptr = val``
8912 - add: ``*ptr = *ptr + val``
8913 - sub: ``*ptr = *ptr - val``
8914 - and: ``*ptr = *ptr & val``
8915 - nand: ``*ptr = ~(*ptr & val)``
8916 - or: ``*ptr = *ptr | val``
8917 - xor: ``*ptr = *ptr ^ val``
8918 - max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison)
8919 - min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison)
8920 - umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned
8922 - umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned
8924 - fadd: ``*ptr = *ptr + val`` (using floating point arithmetic)
8925 - fsub: ``*ptr = *ptr - val`` (using floating point arithmetic)
8930 .. code-block:: llvm
8932 %old = atomicrmw add i32* %ptr, i32 1 acquire ; yields i32
8934 .. _i_getelementptr:
8936 '``getelementptr``' Instruction
8937 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8944 <result> = getelementptr <ty>, <ty>* <ptrval>{, [inrange] <ty> <idx>}*
8945 <result> = getelementptr inbounds <ty>, <ty>* <ptrval>{, [inrange] <ty> <idx>}*
8946 <result> = getelementptr <ty>, <ptr vector> <ptrval>, [inrange] <vector index type> <idx>
8951 The '``getelementptr``' instruction is used to get the address of a
8952 subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs
8953 address calculation only and does not access memory. The instruction can also
8954 be used to calculate a vector of such addresses.
8959 The first argument is always a type used as the basis for the calculations.
8960 The second argument is always a pointer or a vector of pointers, and is the
8961 base address to start from. The remaining arguments are indices
8962 that indicate which of the elements of the aggregate object are indexed.
8963 The interpretation of each index is dependent on the type being indexed
8964 into. The first index always indexes the pointer value given as the
8965 second argument, the second index indexes a value of the type pointed to
8966 (not necessarily the value directly pointed to, since the first index
8967 can be non-zero), etc. The first type indexed into must be a pointer
8968 value, subsequent types can be arrays, vectors, and structs. Note that
8969 subsequent types being indexed into can never be pointers, since that
8970 would require loading the pointer before continuing calculation.
8972 The type of each index argument depends on the type it is indexing into.
8973 When indexing into a (optionally packed) structure, only ``i32`` integer
8974 **constants** are allowed (when using a vector of indices they must all
8975 be the **same** ``i32`` integer constant). When indexing into an array,
8976 pointer or vector, integers of any width are allowed, and they are not
8977 required to be constant. These integers are treated as signed values
8980 For example, let's consider a C code fragment and how it gets compiled
8996 int *foo(struct ST *s) {
8997 return &s[1].Z.B[5][13];
9000 The LLVM code generated by Clang is:
9002 .. code-block:: llvm
9004 %struct.RT = type { i8, [10 x [20 x i32]], i8 }
9005 %struct.ST = type { i32, double, %struct.RT }
9007 define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp {
9009 %arrayidx = getelementptr inbounds %struct.ST, %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13
9016 In the example above, the first index is indexing into the
9017 '``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``'
9018 = '``{ i32, double, %struct.RT }``' type, a structure. The second index
9019 indexes into the third element of the structure, yielding a
9020 '``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another
9021 structure. The third index indexes into the second element of the
9022 structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two
9023 dimensions of the array are subscripted into, yielding an '``i32``'
9024 type. The '``getelementptr``' instruction returns a pointer to this
9025 element, thus computing a value of '``i32*``' type.
9027 Note that it is perfectly legal to index partially through a structure,
9028 returning a pointer to an inner element. Because of this, the LLVM code
9029 for the given testcase is equivalent to:
9031 .. code-block:: llvm
9033 define i32* @foo(%struct.ST* %s) {
9034 %t1 = getelementptr %struct.ST, %struct.ST* %s, i32 1 ; yields %struct.ST*:%t1
9035 %t2 = getelementptr %struct.ST, %struct.ST* %t1, i32 0, i32 2 ; yields %struct.RT*:%t2
9036 %t3 = getelementptr %struct.RT, %struct.RT* %t2, i32 0, i32 1 ; yields [10 x [20 x i32]]*:%t3
9037 %t4 = getelementptr [10 x [20 x i32]], [10 x [20 x i32]]* %t3, i32 0, i32 5 ; yields [20 x i32]*:%t4
9038 %t5 = getelementptr [20 x i32], [20 x i32]* %t4, i32 0, i32 13 ; yields i32*:%t5
9042 If the ``inbounds`` keyword is present, the result value of the
9043 ``getelementptr`` is a :ref:`poison value <poisonvalues>` if the base
9044 pointer is not an *in bounds* address of an allocated object, or if any
9045 of the addresses that would be formed by successive addition of the
9046 offsets implied by the indices to the base address with infinitely
9047 precise signed arithmetic are not an *in bounds* address of that
9048 allocated object. The *in bounds* addresses for an allocated object are
9049 all the addresses that point into the object, plus the address one byte
9050 past the end. The only *in bounds* address for a null pointer in the
9051 default address-space is the null pointer itself. In cases where the
9052 base is a vector of pointers the ``inbounds`` keyword applies to each
9053 of the computations element-wise.
9055 If the ``inbounds`` keyword is not present, the offsets are added to the
9056 base address with silently-wrapping two's complement arithmetic. If the
9057 offsets have a different width from the pointer, they are sign-extended
9058 or truncated to the width of the pointer. The result value of the
9059 ``getelementptr`` may be outside the object pointed to by the base
9060 pointer. The result value may not necessarily be used to access memory
9061 though, even if it happens to point into allocated storage. See the
9062 :ref:`Pointer Aliasing Rules <pointeraliasing>` section for more
9065 If the ``inrange`` keyword is present before any index, loading from or
9066 storing to any pointer derived from the ``getelementptr`` has undefined
9067 behavior if the load or store would access memory outside of the bounds of
9068 the element selected by the index marked as ``inrange``. The result of a
9069 pointer comparison or ``ptrtoint`` (including ``ptrtoint``-like operations
9070 involving memory) involving a pointer derived from a ``getelementptr`` with
9071 the ``inrange`` keyword is undefined, with the exception of comparisons
9072 in the case where both operands are in the range of the element selected
9073 by the ``inrange`` keyword, inclusive of the address one past the end of
9074 that element. Note that the ``inrange`` keyword is currently only allowed
9075 in constant ``getelementptr`` expressions.
9077 The getelementptr instruction is often confusing. For some more insight
9078 into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`.
9083 .. code-block:: llvm
9085 ; yields [12 x i8]*:aptr
9086 %aptr = getelementptr {i32, [12 x i8]}, {i32, [12 x i8]}* %saptr, i64 0, i32 1
9088 %vptr = getelementptr {i32, <2 x i8>}, {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1
9090 %eptr = getelementptr [12 x i8], [12 x i8]* %aptr, i64 0, i32 1
9092 %iptr = getelementptr [10 x i32], [10 x i32]* @arr, i16 0, i16 0
9097 The ``getelementptr`` returns a vector of pointers, instead of a single address,
9098 when one or more of its arguments is a vector. In such cases, all vector
9099 arguments should have the same number of elements, and every scalar argument
9100 will be effectively broadcast into a vector during address calculation.
9102 .. code-block:: llvm
9104 ; All arguments are vectors:
9105 ; A[i] = ptrs[i] + offsets[i]*sizeof(i8)
9106 %A = getelementptr i8, <4 x i8*> %ptrs, <4 x i64> %offsets
9108 ; Add the same scalar offset to each pointer of a vector:
9109 ; A[i] = ptrs[i] + offset*sizeof(i8)
9110 %A = getelementptr i8, <4 x i8*> %ptrs, i64 %offset
9112 ; Add distinct offsets to the same pointer:
9113 ; A[i] = ptr + offsets[i]*sizeof(i8)
9114 %A = getelementptr i8, i8* %ptr, <4 x i64> %offsets
9116 ; In all cases described above the type of the result is <4 x i8*>
9118 The two following instructions are equivalent:
9120 .. code-block:: llvm
9122 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1,
9123 <4 x i32> <i32 2, i32 2, i32 2, i32 2>,
9124 <4 x i32> <i32 1, i32 1, i32 1, i32 1>,
9126 <4 x i64> <i64 13, i64 13, i64 13, i64 13>
9128 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1,
9129 i32 2, i32 1, <4 x i32> %ind4, i64 13
9131 Let's look at the C code, where the vector version of ``getelementptr``
9136 // Let's assume that we vectorize the following loop:
9137 double *A, *B; int *C;
9138 for (int i = 0; i < size; ++i) {
9142 .. code-block:: llvm
9144 ; get pointers for 8 elements from array B
9145 %ptrs = getelementptr double, double* %B, <8 x i32> %C
9146 ; load 8 elements from array B into A
9147 %A = call <8 x double> @llvm.masked.gather.v8f64.v8p0f64(<8 x double*> %ptrs,
9148 i32 8, <8 x i1> %mask, <8 x double> %passthru)
9150 Conversion Operations
9151 ---------------------
9153 The instructions in this category are the conversion instructions
9154 (casting) which all take a single operand and a type. They perform
9155 various bit conversions on the operand.
9159 '``trunc .. to``' Instruction
9160 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9167 <result> = trunc <ty> <value> to <ty2> ; yields ty2
9172 The '``trunc``' instruction truncates its operand to the type ``ty2``.
9177 The '``trunc``' instruction takes a value to trunc, and a type to trunc
9178 it to. Both types must be of :ref:`integer <t_integer>` types, or vectors
9179 of the same number of integers. The bit size of the ``value`` must be
9180 larger than the bit size of the destination type, ``ty2``. Equal sized
9181 types are not allowed.
9186 The '``trunc``' instruction truncates the high order bits in ``value``
9187 and converts the remaining bits to ``ty2``. Since the source size must
9188 be larger than the destination size, ``trunc`` cannot be a *no-op cast*.
9189 It will always truncate bits.
9194 .. code-block:: llvm
9196 %X = trunc i32 257 to i8 ; yields i8:1
9197 %Y = trunc i32 123 to i1 ; yields i1:true
9198 %Z = trunc i32 122 to i1 ; yields i1:false
9199 %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
9203 '``zext .. to``' Instruction
9204 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9211 <result> = zext <ty> <value> to <ty2> ; yields ty2
9216 The '``zext``' instruction zero extends its operand to type ``ty2``.
9221 The '``zext``' instruction takes a value to cast, and a type to cast it
9222 to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
9223 the same number of integers. The bit size of the ``value`` must be
9224 smaller than the bit size of the destination type, ``ty2``.
9229 The ``zext`` fills the high order bits of the ``value`` with zero bits
9230 until it reaches the size of the destination type, ``ty2``.
9232 When zero extending from i1, the result will always be either 0 or 1.
9237 .. code-block:: llvm
9239 %X = zext i32 257 to i64 ; yields i64:257
9240 %Y = zext i1 true to i32 ; yields i32:1
9241 %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
9245 '``sext .. to``' Instruction
9246 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9253 <result> = sext <ty> <value> to <ty2> ; yields ty2
9258 The '``sext``' sign extends ``value`` to the type ``ty2``.
9263 The '``sext``' instruction takes a value to cast, and a type to cast it
9264 to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
9265 the same number of integers. The bit size of the ``value`` must be
9266 smaller than the bit size of the destination type, ``ty2``.
9271 The '``sext``' instruction performs a sign extension by copying the sign
9272 bit (highest order bit) of the ``value`` until it reaches the bit size
9273 of the type ``ty2``.
9275 When sign extending from i1, the extension always results in -1 or 0.
9280 .. code-block:: llvm
9282 %X = sext i8 -1 to i16 ; yields i16 :65535
9283 %Y = sext i1 true to i32 ; yields i32:-1
9284 %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
9286 '``fptrunc .. to``' Instruction
9287 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9294 <result> = fptrunc <ty> <value> to <ty2> ; yields ty2
9299 The '``fptrunc``' instruction truncates ``value`` to type ``ty2``.
9304 The '``fptrunc``' instruction takes a :ref:`floating-point <t_floating>`
9305 value to cast and a :ref:`floating-point <t_floating>` type to cast it to.
9306 The size of ``value`` must be larger than the size of ``ty2``. This
9307 implies that ``fptrunc`` cannot be used to make a *no-op cast*.
9312 The '``fptrunc``' instruction casts a ``value`` from a larger
9313 :ref:`floating-point <t_floating>` type to a smaller :ref:`floating-point
9315 This instruction is assumed to execute in the default :ref:`floating-point
9316 environment <floatenv>`.
9321 .. code-block:: llvm
9323 %X = fptrunc double 16777217.0 to float ; yields float:16777216.0
9324 %Y = fptrunc double 1.0E+300 to half ; yields half:+infinity
9326 '``fpext .. to``' Instruction
9327 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9334 <result> = fpext <ty> <value> to <ty2> ; yields ty2
9339 The '``fpext``' extends a floating-point ``value`` to a larger floating-point
9345 The '``fpext``' instruction takes a :ref:`floating-point <t_floating>`
9346 ``value`` to cast, and a :ref:`floating-point <t_floating>` type to cast it
9347 to. The source type must be smaller than the destination type.
9352 The '``fpext``' instruction extends the ``value`` from a smaller
9353 :ref:`floating-point <t_floating>` type to a larger :ref:`floating-point
9354 <t_floating>` type. The ``fpext`` cannot be used to make a
9355 *no-op cast* because it always changes bits. Use ``bitcast`` to make a
9356 *no-op cast* for a floating-point cast.
9361 .. code-block:: llvm
9363 %X = fpext float 3.125 to double ; yields double:3.125000e+00
9364 %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000
9366 '``fptoui .. to``' Instruction
9367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9374 <result> = fptoui <ty> <value> to <ty2> ; yields ty2
9379 The '``fptoui``' converts a floating-point ``value`` to its unsigned
9380 integer equivalent of type ``ty2``.
9385 The '``fptoui``' instruction takes a value to cast, which must be a
9386 scalar or vector :ref:`floating-point <t_floating>` value, and a type to
9387 cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
9388 ``ty`` is a vector floating-point type, ``ty2`` must be a vector integer
9389 type with the same number of elements as ``ty``
9394 The '``fptoui``' instruction converts its :ref:`floating-point
9395 <t_floating>` operand into the nearest (rounding towards zero)
9396 unsigned integer value. If the value cannot fit in ``ty2``, the result
9397 is a :ref:`poison value <poisonvalues>`.
9402 .. code-block:: llvm
9404 %X = fptoui double 123.0 to i32 ; yields i32:123
9405 %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1
9406 %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1
9408 '``fptosi .. to``' Instruction
9409 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9416 <result> = fptosi <ty> <value> to <ty2> ; yields ty2
9421 The '``fptosi``' instruction converts :ref:`floating-point <t_floating>`
9422 ``value`` to type ``ty2``.
9427 The '``fptosi``' instruction takes a value to cast, which must be a
9428 scalar or vector :ref:`floating-point <t_floating>` value, and a type to
9429 cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
9430 ``ty`` is a vector floating-point type, ``ty2`` must be a vector integer
9431 type with the same number of elements as ``ty``
9436 The '``fptosi``' instruction converts its :ref:`floating-point
9437 <t_floating>` operand into the nearest (rounding towards zero)
9438 signed integer value. If the value cannot fit in ``ty2``, the result
9439 is a :ref:`poison value <poisonvalues>`.
9444 .. code-block:: llvm
9446 %X = fptosi double -123.0 to i32 ; yields i32:-123
9447 %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1
9448 %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1
9450 '``uitofp .. to``' Instruction
9451 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9458 <result> = uitofp <ty> <value> to <ty2> ; yields ty2
9463 The '``uitofp``' instruction regards ``value`` as an unsigned integer
9464 and converts that value to the ``ty2`` type.
9469 The '``uitofp``' instruction takes a value to cast, which must be a
9470 scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
9471 ``ty2``, which must be an :ref:`floating-point <t_floating>` type. If
9472 ``ty`` is a vector integer type, ``ty2`` must be a vector floating-point
9473 type with the same number of elements as ``ty``
9478 The '``uitofp``' instruction interprets its operand as an unsigned
9479 integer quantity and converts it to the corresponding floating-point
9480 value. If the value cannot be exactly represented, it is rounded using
9481 the default rounding mode.
9487 .. code-block:: llvm
9489 %X = uitofp i32 257 to float ; yields float:257.0
9490 %Y = uitofp i8 -1 to double ; yields double:255.0
9492 '``sitofp .. to``' Instruction
9493 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9500 <result> = sitofp <ty> <value> to <ty2> ; yields ty2
9505 The '``sitofp``' instruction regards ``value`` as a signed integer and
9506 converts that value to the ``ty2`` type.
9511 The '``sitofp``' instruction takes a value to cast, which must be a
9512 scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
9513 ``ty2``, which must be an :ref:`floating-point <t_floating>` type. If
9514 ``ty`` is a vector integer type, ``ty2`` must be a vector floating-point
9515 type with the same number of elements as ``ty``
9520 The '``sitofp``' instruction interprets its operand as a signed integer
9521 quantity and converts it to the corresponding floating-point value. If the
9522 value cannot be exactly represented, it is rounded using the default rounding
9528 .. code-block:: llvm
9530 %X = sitofp i32 257 to float ; yields float:257.0
9531 %Y = sitofp i8 -1 to double ; yields double:-1.0
9535 '``ptrtoint .. to``' Instruction
9536 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9543 <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2
9548 The '``ptrtoint``' instruction converts the pointer or a vector of
9549 pointers ``value`` to the integer (or vector of integers) type ``ty2``.
9554 The '``ptrtoint``' instruction takes a ``value`` to cast, which must be
9555 a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a
9556 type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or
9557 a vector of integers type.
9562 The '``ptrtoint``' instruction converts ``value`` to integer type
9563 ``ty2`` by interpreting the pointer value as an integer and either
9564 truncating or zero extending that value to the size of the integer type.
9565 If ``value`` is smaller than ``ty2`` then a zero extension is done. If
9566 ``value`` is larger than ``ty2`` then a truncation is done. If they are
9567 the same size, then nothing is done (*no-op cast*) other than a type
9573 .. code-block:: llvm
9575 %X = ptrtoint i32* %P to i8 ; yields truncation on 32-bit architecture
9576 %Y = ptrtoint i32* %P to i64 ; yields zero extension on 32-bit architecture
9577 %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture
9581 '``inttoptr .. to``' Instruction
9582 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9589 <result> = inttoptr <ty> <value> to <ty2> ; yields ty2
9594 The '``inttoptr``' instruction converts an integer ``value`` to a
9595 pointer type, ``ty2``.
9600 The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to
9601 cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>`
9607 The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by
9608 applying either a zero extension or a truncation depending on the size
9609 of the integer ``value``. If ``value`` is larger than the size of a
9610 pointer then a truncation is done. If ``value`` is smaller than the size
9611 of a pointer then a zero extension is done. If they are the same size,
9612 nothing is done (*no-op cast*).
9617 .. code-block:: llvm
9619 %X = inttoptr i32 255 to i32* ; yields zero extension on 64-bit architecture
9620 %Y = inttoptr i32 255 to i32* ; yields no-op on 32-bit architecture
9621 %Z = inttoptr i64 0 to i32* ; yields truncation on 32-bit architecture
9622 %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers
9626 '``bitcast .. to``' Instruction
9627 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9634 <result> = bitcast <ty> <value> to <ty2> ; yields ty2
9639 The '``bitcast``' instruction converts ``value`` to type ``ty2`` without
9645 The '``bitcast``' instruction takes a value to cast, which must be a
9646 non-aggregate first class value, and a type to cast it to, which must
9647 also be a non-aggregate :ref:`first class <t_firstclass>` type. The
9648 bit sizes of ``value`` and the destination type, ``ty2``, must be
9649 identical. If the source type is a pointer, the destination type must
9650 also be a pointer of the same size. This instruction supports bitwise
9651 conversion of vectors to integers and to vectors of other types (as
9652 long as they have the same size).
9657 The '``bitcast``' instruction converts ``value`` to type ``ty2``. It
9658 is always a *no-op cast* because no bits change with this
9659 conversion. The conversion is done as if the ``value`` had been stored
9660 to memory and read back as type ``ty2``. Pointer (or vector of
9661 pointers) types may only be converted to other pointer (or vector of
9662 pointers) types with the same address space through this instruction.
9663 To convert pointers to other types, use the :ref:`inttoptr <i_inttoptr>`
9664 or :ref:`ptrtoint <i_ptrtoint>` instructions first.
9669 .. code-block:: text
9671 %X = bitcast i8 255 to i8 ; yields i8 :-1
9672 %Y = bitcast i32* %x to sint* ; yields sint*:%x
9673 %Z = bitcast <2 x int> %V to i64; ; yields i64: %V
9674 %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
9676 .. _i_addrspacecast:
9678 '``addrspacecast .. to``' Instruction
9679 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9686 <result> = addrspacecast <pty> <ptrval> to <pty2> ; yields pty2
9691 The '``addrspacecast``' instruction converts ``ptrval`` from ``pty`` in
9692 address space ``n`` to type ``pty2`` in address space ``m``.
9697 The '``addrspacecast``' instruction takes a pointer or vector of pointer value
9698 to cast and a pointer type to cast it to, which must have a different
9704 The '``addrspacecast``' instruction converts the pointer value
9705 ``ptrval`` to type ``pty2``. It can be a *no-op cast* or a complex
9706 value modification, depending on the target and the address space
9707 pair. Pointer conversions within the same address space must be
9708 performed with the ``bitcast`` instruction. Note that if the address space
9709 conversion is legal then both result and operand refer to the same memory
9715 .. code-block:: llvm
9717 %X = addrspacecast i32* %x to i32 addrspace(1)* ; yields i32 addrspace(1)*:%x
9718 %Y = addrspacecast i32 addrspace(1)* %y to i64 addrspace(2)* ; yields i64 addrspace(2)*:%y
9719 %Z = addrspacecast <4 x i32*> %z to <4 x float addrspace(3)*> ; yields <4 x float addrspace(3)*>:%z
9726 The instructions in this category are the "miscellaneous" instructions,
9727 which defy better classification.
9731 '``icmp``' Instruction
9732 ^^^^^^^^^^^^^^^^^^^^^^
9739 <result> = icmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
9744 The '``icmp``' instruction returns a boolean value or a vector of
9745 boolean values based on comparison of its two integer, integer vector,
9746 pointer, or pointer vector operands.
9751 The '``icmp``' instruction takes three operands. The first operand is
9752 the condition code indicating the kind of comparison to perform. It is
9753 not a value, just a keyword. The possible condition codes are:
9756 #. ``ne``: not equal
9757 #. ``ugt``: unsigned greater than
9758 #. ``uge``: unsigned greater or equal
9759 #. ``ult``: unsigned less than
9760 #. ``ule``: unsigned less or equal
9761 #. ``sgt``: signed greater than
9762 #. ``sge``: signed greater or equal
9763 #. ``slt``: signed less than
9764 #. ``sle``: signed less or equal
9766 The remaining two arguments must be :ref:`integer <t_integer>` or
9767 :ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They
9768 must also be identical types.
9773 The '``icmp``' compares ``op1`` and ``op2`` according to the condition
9774 code given as ``cond``. The comparison performed always yields either an
9775 :ref:`i1 <t_integer>` or vector of ``i1`` result, as follows:
9777 #. ``eq``: yields ``true`` if the operands are equal, ``false``
9778 otherwise. No sign interpretation is necessary or performed.
9779 #. ``ne``: yields ``true`` if the operands are unequal, ``false``
9780 otherwise. No sign interpretation is necessary or performed.
9781 #. ``ugt``: interprets the operands as unsigned values and yields
9782 ``true`` if ``op1`` is greater than ``op2``.
9783 #. ``uge``: interprets the operands as unsigned values and yields
9784 ``true`` if ``op1`` is greater than or equal to ``op2``.
9785 #. ``ult``: interprets the operands as unsigned values and yields
9786 ``true`` if ``op1`` is less than ``op2``.
9787 #. ``ule``: interprets the operands as unsigned values and yields
9788 ``true`` if ``op1`` is less than or equal to ``op2``.
9789 #. ``sgt``: interprets the operands as signed values and yields ``true``
9790 if ``op1`` is greater than ``op2``.
9791 #. ``sge``: interprets the operands as signed values and yields ``true``
9792 if ``op1`` is greater than or equal to ``op2``.
9793 #. ``slt``: interprets the operands as signed values and yields ``true``
9794 if ``op1`` is less than ``op2``.
9795 #. ``sle``: interprets the operands as signed values and yields ``true``
9796 if ``op1`` is less than or equal to ``op2``.
9798 If the operands are :ref:`pointer <t_pointer>` typed, the pointer values
9799 are compared as if they were integers.
9801 If the operands are integer vectors, then they are compared element by
9802 element. The result is an ``i1`` vector with the same number of elements
9803 as the values being compared. Otherwise, the result is an ``i1``.
9808 .. code-block:: text
9810 <result> = icmp eq i32 4, 5 ; yields: result=false
9811 <result> = icmp ne float* %X, %X ; yields: result=false
9812 <result> = icmp ult i16 4, 5 ; yields: result=true
9813 <result> = icmp sgt i16 4, 5 ; yields: result=false
9814 <result> = icmp ule i16 -4, 5 ; yields: result=false
9815 <result> = icmp sge i16 4, 5 ; yields: result=false
9819 '``fcmp``' Instruction
9820 ^^^^^^^^^^^^^^^^^^^^^^
9827 <result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
9832 The '``fcmp``' instruction returns a boolean value or vector of boolean
9833 values based on comparison of its operands.
9835 If the operands are floating-point scalars, then the result type is a
9836 boolean (:ref:`i1 <t_integer>`).
9838 If the operands are floating-point vectors, then the result type is a
9839 vector of boolean with the same number of elements as the operands being
9845 The '``fcmp``' instruction takes three operands. The first operand is
9846 the condition code indicating the kind of comparison to perform. It is
9847 not a value, just a keyword. The possible condition codes are:
9849 #. ``false``: no comparison, always returns false
9850 #. ``oeq``: ordered and equal
9851 #. ``ogt``: ordered and greater than
9852 #. ``oge``: ordered and greater than or equal
9853 #. ``olt``: ordered and less than
9854 #. ``ole``: ordered and less than or equal
9855 #. ``one``: ordered and not equal
9856 #. ``ord``: ordered (no nans)
9857 #. ``ueq``: unordered or equal
9858 #. ``ugt``: unordered or greater than
9859 #. ``uge``: unordered or greater than or equal
9860 #. ``ult``: unordered or less than
9861 #. ``ule``: unordered or less than or equal
9862 #. ``une``: unordered or not equal
9863 #. ``uno``: unordered (either nans)
9864 #. ``true``: no comparison, always returns true
9866 *Ordered* means that neither operand is a QNAN while *unordered* means
9867 that either operand may be a QNAN.
9869 Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating-point
9870 <t_floating>` type or a :ref:`vector <t_vector>` of floating-point type.
9871 They must have identical types.
9876 The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the
9877 condition code given as ``cond``. If the operands are vectors, then the
9878 vectors are compared element by element. Each comparison performed
9879 always yields an :ref:`i1 <t_integer>` result, as follows:
9881 #. ``false``: always yields ``false``, regardless of operands.
9882 #. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1``
9883 is equal to ``op2``.
9884 #. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1``
9885 is greater than ``op2``.
9886 #. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1``
9887 is greater than or equal to ``op2``.
9888 #. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1``
9889 is less than ``op2``.
9890 #. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1``
9891 is less than or equal to ``op2``.
9892 #. ``one``: yields ``true`` if both operands are not a QNAN and ``op1``
9893 is not equal to ``op2``.
9894 #. ``ord``: yields ``true`` if both operands are not a QNAN.
9895 #. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is
9897 #. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is
9898 greater than ``op2``.
9899 #. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is
9900 greater than or equal to ``op2``.
9901 #. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is
9903 #. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is
9904 less than or equal to ``op2``.
9905 #. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is
9906 not equal to ``op2``.
9907 #. ``uno``: yields ``true`` if either operand is a QNAN.
9908 #. ``true``: always yields ``true``, regardless of operands.
9910 The ``fcmp`` instruction can also optionally take any number of
9911 :ref:`fast-math flags <fastmath>`, which are optimization hints to enable
9912 otherwise unsafe floating-point optimizations.
9914 Any set of fast-math flags are legal on an ``fcmp`` instruction, but the
9915 only flags that have any effect on its semantics are those that allow
9916 assumptions to be made about the values of input arguments; namely
9917 ``nnan``, ``ninf``, and ``reassoc``. See :ref:`fastmath` for more information.
9922 .. code-block:: text
9924 <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false
9925 <result> = fcmp one float 4.0, 5.0 ; yields: result=true
9926 <result> = fcmp olt float 4.0, 5.0 ; yields: result=true
9927 <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false
9931 '``phi``' Instruction
9932 ^^^^^^^^^^^^^^^^^^^^^
9939 <result> = phi <ty> [ <val0>, <label0>], ...
9944 The '``phi``' instruction is used to implement the φ node in the SSA
9945 graph representing the function.
9950 The type of the incoming values is specified with the first type field.
9951 After this, the '``phi``' instruction takes a list of pairs as
9952 arguments, with one pair for each predecessor basic block of the current
9953 block. Only values of :ref:`first class <t_firstclass>` type may be used as
9954 the value arguments to the PHI node. Only labels may be used as the
9957 There must be no non-phi instructions between the start of a basic block
9958 and the PHI instructions: i.e. PHI instructions must be first in a basic
9961 For the purposes of the SSA form, the use of each incoming value is
9962 deemed to occur on the edge from the corresponding predecessor block to
9963 the current block (but after any definition of an '``invoke``'
9964 instruction's return value on the same edge).
9969 At runtime, the '``phi``' instruction logically takes on the value
9970 specified by the pair corresponding to the predecessor basic block that
9971 executed just prior to the current block.
9976 .. code-block:: llvm
9978 Loop: ; Infinite loop that counts from 0 on up...
9979 %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
9980 %nextindvar = add i32 %indvar, 1
9985 '``select``' Instruction
9986 ^^^^^^^^^^^^^^^^^^^^^^^^
9993 <result> = select [fast-math flags] selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty
9995 selty is either i1 or {<N x i1>}
10000 The '``select``' instruction is used to choose one value based on a
10001 condition, without IR-level branching.
10006 The '``select``' instruction requires an 'i1' value or a vector of 'i1'
10007 values indicating the condition, and two values of the same :ref:`first
10008 class <t_firstclass>` type.
10010 #. The optional ``fast-math flags`` marker indicates that the select has one or more
10011 :ref:`fast-math flags <fastmath>`. These are optimization hints to enable
10012 otherwise unsafe floating-point optimizations. Fast-math flags are only valid
10013 for selects that return a floating-point scalar or vector type.
10018 If the condition is an i1 and it evaluates to 1, the instruction returns
10019 the first value argument; otherwise, it returns the second value
10022 If the condition is a vector of i1, then the value arguments must be
10023 vectors of the same size, and the selection is done element by element.
10025 If the condition is an i1 and the value arguments are vectors of the
10026 same size, then an entire vector is selected.
10031 .. code-block:: llvm
10033 %X = select i1 true, i8 17, i8 42 ; yields i8:17
10037 '``call``' Instruction
10038 ^^^^^^^^^^^^^^^^^^^^^^
10045 <result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)]
10046 [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ]
10051 The '``call``' instruction represents a simple function call.
10056 This instruction requires several arguments:
10058 #. The optional ``tail`` and ``musttail`` markers indicate that the optimizers
10059 should perform tail call optimization. The ``tail`` marker is a hint that
10060 `can be ignored <CodeGenerator.html#sibcallopt>`_. The ``musttail`` marker
10061 means that the call must be tail call optimized in order for the program to
10062 be correct. The ``musttail`` marker provides these guarantees:
10064 #. The call will not cause unbounded stack growth if it is part of a
10065 recursive cycle in the call graph.
10066 #. Arguments with the :ref:`inalloca <attr_inalloca>` attribute are
10067 forwarded in place.
10068 #. If the musttail call appears in a function with the ``"thunk"`` attribute
10069 and the caller and callee both have varargs, than any unprototyped
10070 arguments in register or memory are forwarded to the callee. Similarly,
10071 the return value of the callee is returned the the caller's caller, even
10072 if a void return type is in use.
10074 Both markers imply that the callee does not access allocas from the caller.
10075 The ``tail`` marker additionally implies that the callee does not access
10076 varargs from the caller. Calls marked ``musttail`` must obey the following
10079 - The call must immediately precede a :ref:`ret <i_ret>` instruction,
10080 or a pointer bitcast followed by a ret instruction.
10081 - The ret instruction must return the (possibly bitcasted) value
10082 produced by the call or void.
10083 - The caller and callee prototypes must match. Pointer types of
10084 parameters or return types may differ in pointee type, but not
10086 - The calling conventions of the caller and callee must match.
10087 - All ABI-impacting function attributes, such as sret, byval, inreg,
10088 returned, and inalloca, must match.
10089 - The callee must be varargs iff the caller is varargs. Bitcasting a
10090 non-varargs function to the appropriate varargs type is legal so
10091 long as the non-varargs prefixes obey the other rules.
10093 Tail call optimization for calls marked ``tail`` is guaranteed to occur if
10094 the following conditions are met:
10096 - Caller and callee both have the calling convention ``fastcc``.
10097 - The call is in tail position (ret immediately follows call and ret
10098 uses value of call or is void).
10099 - Option ``-tailcallopt`` is enabled, or
10100 ``llvm::GuaranteedTailCallOpt`` is ``true``.
10101 - `Platform-specific constraints are
10102 met. <CodeGenerator.html#tailcallopt>`_
10104 #. The optional ``notail`` marker indicates that the optimizers should not add
10105 ``tail`` or ``musttail`` markers to the call. It is used to prevent tail
10106 call optimization from being performed on the call.
10108 #. The optional ``fast-math flags`` marker indicates that the call has one or more
10109 :ref:`fast-math flags <fastmath>`, which are optimization hints to enable
10110 otherwise unsafe floating-point optimizations. Fast-math flags are only valid
10111 for calls that return a floating-point scalar or vector type.
10113 #. The optional "cconv" marker indicates which :ref:`calling
10114 convention <callingconv>` the call should use. If none is
10115 specified, the call defaults to using C calling conventions. The
10116 calling convention of the call must match the calling convention of
10117 the target function, or else the behavior is undefined.
10118 #. The optional :ref:`Parameter Attributes <paramattrs>` list for return
10119 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
10121 #. The optional addrspace attribute can be used to indicate the address space
10122 of the called function. If it is not specified, the program address space
10123 from the :ref:`datalayout string<langref_datalayout>` will be used.
10124 #. '``ty``': the type of the call instruction itself which is also the
10125 type of the return value. Functions that return no value are marked
10127 #. '``fnty``': shall be the signature of the function being called. The
10128 argument types must match the types implied by this signature. This
10129 type can be omitted if the function is not varargs.
10130 #. '``fnptrval``': An LLVM value containing a pointer to a function to
10131 be called. In most cases, this is a direct function call, but
10132 indirect ``call``'s are just as possible, calling an arbitrary pointer
10134 #. '``function args``': argument list whose types match the function
10135 signature argument types and parameter attributes. All arguments must
10136 be of :ref:`first class <t_firstclass>` type. If the function signature
10137 indicates the function accepts a variable number of arguments, the
10138 extra arguments can be specified.
10139 #. The optional :ref:`function attributes <fnattrs>` list.
10140 #. The optional :ref:`operand bundles <opbundles>` list.
10145 The '``call``' instruction is used to cause control flow to transfer to
10146 a specified function, with its incoming arguments bound to the specified
10147 values. Upon a '``ret``' instruction in the called function, control
10148 flow continues with the instruction after the function call, and the
10149 return value of the function is bound to the result argument.
10154 .. code-block:: llvm
10156 %retval = call i32 @test(i32 %argc)
10157 call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) ; yields i32
10158 %X = tail call i32 @foo() ; yields i32
10159 %Y = tail call fastcc i32 @foo() ; yields i32
10160 call void %foo(i8 97 signext)
10162 %struct.A = type { i32, i8 }
10163 %r = call %struct.A @foo() ; yields { i32, i8 }
10164 %gr = extractvalue %struct.A %r, 0 ; yields i32
10165 %gr1 = extractvalue %struct.A %r, 1 ; yields i8
10166 %Z = call void @foo() noreturn ; indicates that %foo never returns normally
10167 %ZZ = call zeroext i32 @bar() ; Return value is %zero extended
10169 llvm treats calls to some functions with names and arguments that match
10170 the standard C99 library as being the C99 library functions, and may
10171 perform optimizations or generate code for them under that assumption.
10172 This is something we'd like to change in the future to provide better
10173 support for freestanding environments and non-C-based languages.
10177 '``va_arg``' Instruction
10178 ^^^^^^^^^^^^^^^^^^^^^^^^
10185 <resultval> = va_arg <va_list*> <arglist>, <argty>
10190 The '``va_arg``' instruction is used to access arguments passed through
10191 the "variable argument" area of a function call. It is used to implement
10192 the ``va_arg`` macro in C.
10197 This instruction takes a ``va_list*`` value and the type of the
10198 argument. It returns a value of the specified argument type and
10199 increments the ``va_list`` to point to the next argument. The actual
10200 type of ``va_list`` is target specific.
10205 The '``va_arg``' instruction loads an argument of the specified type
10206 from the specified ``va_list`` and causes the ``va_list`` to point to
10207 the next argument. For more information, see the variable argument
10208 handling :ref:`Intrinsic Functions <int_varargs>`.
10210 It is legal for this instruction to be called in a function which does
10211 not take a variable number of arguments, for example, the ``vfprintf``
10214 ``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic
10215 function <intrinsics>` because it takes a type as an argument.
10220 See the :ref:`variable argument processing <int_varargs>` section.
10222 Note that the code generator does not yet fully support va\_arg on many
10223 targets. Also, it does not currently support va\_arg with aggregate
10224 types on any target.
10228 '``landingpad``' Instruction
10229 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10236 <resultval> = landingpad <resultty> <clause>+
10237 <resultval> = landingpad <resultty> cleanup <clause>*
10239 <clause> := catch <type> <value>
10240 <clause> := filter <array constant type> <array constant>
10245 The '``landingpad``' instruction is used by `LLVM's exception handling
10246 system <ExceptionHandling.html#overview>`_ to specify that a basic block
10247 is a landing pad --- one where the exception lands, and corresponds to the
10248 code found in the ``catch`` portion of a ``try``/``catch`` sequence. It
10249 defines values supplied by the :ref:`personality function <personalityfn>` upon
10250 re-entry to the function. The ``resultval`` has the type ``resultty``.
10256 ``cleanup`` flag indicates that the landing pad block is a cleanup.
10258 A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and
10259 contains the global variable representing the "type" that may be caught
10260 or filtered respectively. Unlike the ``catch`` clause, the ``filter``
10261 clause takes an array constant as its argument. Use
10262 "``[0 x i8**] undef``" for a filter which cannot throw. The
10263 '``landingpad``' instruction must contain *at least* one ``clause`` or
10264 the ``cleanup`` flag.
10269 The '``landingpad``' instruction defines the values which are set by the
10270 :ref:`personality function <personalityfn>` upon re-entry to the function, and
10271 therefore the "result type" of the ``landingpad`` instruction. As with
10272 calling conventions, how the personality function results are
10273 represented in LLVM IR is target specific.
10275 The clauses are applied in order from top to bottom. If two
10276 ``landingpad`` instructions are merged together through inlining, the
10277 clauses from the calling function are appended to the list of clauses.
10278 When the call stack is being unwound due to an exception being thrown,
10279 the exception is compared against each ``clause`` in turn. If it doesn't
10280 match any of the clauses, and the ``cleanup`` flag is not set, then
10281 unwinding continues further up the call stack.
10283 The ``landingpad`` instruction has several restrictions:
10285 - A landing pad block is a basic block which is the unwind destination
10286 of an '``invoke``' instruction.
10287 - A landing pad block must have a '``landingpad``' instruction as its
10288 first non-PHI instruction.
10289 - There can be only one '``landingpad``' instruction within the landing
10291 - A basic block that is not a landing pad block may not include a
10292 '``landingpad``' instruction.
10297 .. code-block:: llvm
10299 ;; A landing pad which can catch an integer.
10300 %res = landingpad { i8*, i32 }
10302 ;; A landing pad that is a cleanup.
10303 %res = landingpad { i8*, i32 }
10305 ;; A landing pad which can catch an integer and can only throw a double.
10306 %res = landingpad { i8*, i32 }
10308 filter [1 x i8**] [@_ZTId]
10312 '``catchpad``' Instruction
10313 ^^^^^^^^^^^^^^^^^^^^^^^^^^
10320 <resultval> = catchpad within <catchswitch> [<args>*]
10325 The '``catchpad``' instruction is used by `LLVM's exception handling
10326 system <ExceptionHandling.html#overview>`_ to specify that a basic block
10327 begins a catch handler --- one where a personality routine attempts to transfer
10328 control to catch an exception.
10333 The ``catchswitch`` operand must always be a token produced by a
10334 :ref:`catchswitch <i_catchswitch>` instruction in a predecessor block. This
10335 ensures that each ``catchpad`` has exactly one predecessor block, and it always
10336 terminates in a ``catchswitch``.
10338 The ``args`` correspond to whatever information the personality routine
10339 requires to know if this is an appropriate handler for the exception. Control
10340 will transfer to the ``catchpad`` if this is the first appropriate handler for
10343 The ``resultval`` has the type :ref:`token <t_token>` and is used to match the
10344 ``catchpad`` to corresponding :ref:`catchrets <i_catchret>` and other nested EH
10350 When the call stack is being unwound due to an exception being thrown, the
10351 exception is compared against the ``args``. If it doesn't match, control will
10352 not reach the ``catchpad`` instruction. The representation of ``args`` is
10353 entirely target and personality function-specific.
10355 Like the :ref:`landingpad <i_landingpad>` instruction, the ``catchpad``
10356 instruction must be the first non-phi of its parent basic block.
10358 The meaning of the tokens produced and consumed by ``catchpad`` and other "pad"
10359 instructions is described in the
10360 `Windows exception handling documentation\ <ExceptionHandling.html#wineh>`_.
10362 When a ``catchpad`` has been "entered" but not yet "exited" (as
10363 described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_),
10364 it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>`
10365 that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`.
10370 .. code-block:: text
10373 %cs = catchswitch within none [label %handler0] unwind to caller
10374 ;; A catch block which can catch an integer.
10376 %tok = catchpad within %cs [i8** @_ZTIi]
10380 '``cleanuppad``' Instruction
10381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10388 <resultval> = cleanuppad within <parent> [<args>*]
10393 The '``cleanuppad``' instruction is used by `LLVM's exception handling
10394 system <ExceptionHandling.html#overview>`_ to specify that a basic block
10395 is a cleanup block --- one where a personality routine attempts to
10396 transfer control to run cleanup actions.
10397 The ``args`` correspond to whatever additional
10398 information the :ref:`personality function <personalityfn>` requires to
10399 execute the cleanup.
10400 The ``resultval`` has the type :ref:`token <t_token>` and is used to
10401 match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`.
10402 The ``parent`` argument is the token of the funclet that contains the
10403 ``cleanuppad`` instruction. If the ``cleanuppad`` is not inside a funclet,
10404 this operand may be the token ``none``.
10409 The instruction takes a list of arbitrary values which are interpreted
10410 by the :ref:`personality function <personalityfn>`.
10415 When the call stack is being unwound due to an exception being thrown,
10416 the :ref:`personality function <personalityfn>` transfers control to the
10417 ``cleanuppad`` with the aid of the personality-specific arguments.
10418 As with calling conventions, how the personality function results are
10419 represented in LLVM IR is target specific.
10421 The ``cleanuppad`` instruction has several restrictions:
10423 - A cleanup block is a basic block which is the unwind destination of
10424 an exceptional instruction.
10425 - A cleanup block must have a '``cleanuppad``' instruction as its
10426 first non-PHI instruction.
10427 - There can be only one '``cleanuppad``' instruction within the
10429 - A basic block that is not a cleanup block may not include a
10430 '``cleanuppad``' instruction.
10432 When a ``cleanuppad`` has been "entered" but not yet "exited" (as
10433 described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_),
10434 it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>`
10435 that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`.
10440 .. code-block:: text
10442 %tok = cleanuppad within %cs []
10446 Intrinsic Functions
10447 ===================
10449 LLVM supports the notion of an "intrinsic function". These functions
10450 have well known names and semantics and are required to follow certain
10451 restrictions. Overall, these intrinsics represent an extension mechanism
10452 for the LLVM language that does not require changing all of the
10453 transformations in LLVM when adding to the language (or the bitcode
10454 reader/writer, the parser, etc...).
10456 Intrinsic function names must all start with an "``llvm.``" prefix. This
10457 prefix is reserved in LLVM for intrinsic names; thus, function names may
10458 not begin with this prefix. Intrinsic functions must always be external
10459 functions: you cannot define the body of intrinsic functions. Intrinsic
10460 functions may only be used in call or invoke instructions: it is illegal
10461 to take the address of an intrinsic function. Additionally, because
10462 intrinsic functions are part of the LLVM language, it is required if any
10463 are added that they be documented here.
10465 Some intrinsic functions can be overloaded, i.e., the intrinsic
10466 represents a family of functions that perform the same operation but on
10467 different data types. Because LLVM can represent over 8 million
10468 different integer types, overloading is used commonly to allow an
10469 intrinsic function to operate on any integer type. One or more of the
10470 argument types or the result type can be overloaded to accept any
10471 integer type. Argument types may also be defined as exactly matching a
10472 previous argument's type or the result type. This allows an intrinsic
10473 function which accepts multiple arguments, but needs all of them to be
10474 of the same type, to only be overloaded with respect to a single
10475 argument or the result.
10477 Overloaded intrinsics will have the names of its overloaded argument
10478 types encoded into its function name, each preceded by a period. Only
10479 those types which are overloaded result in a name suffix. Arguments
10480 whose type is matched against another type do not. For example, the
10481 ``llvm.ctpop`` function can take an integer of any width and returns an
10482 integer of exactly the same integer width. This leads to a family of
10483 functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and
10484 ``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is
10485 overloaded, and only one type suffix is required. Because the argument's
10486 type is matched against the return type, it does not require its own
10489 To learn how to add an intrinsic function, please see the `Extending
10490 LLVM Guide <ExtendingLLVM.html>`_.
10494 Variable Argument Handling Intrinsics
10495 -------------------------------------
10497 Variable argument support is defined in LLVM with the
10498 :ref:`va_arg <i_va_arg>` instruction and these three intrinsic
10499 functions. These functions are related to the similarly named macros
10500 defined in the ``<stdarg.h>`` header file.
10502 All of these functions operate on arguments that use a target-specific
10503 value type "``va_list``". The LLVM assembly language reference manual
10504 does not define what this type is, so all transformations should be
10505 prepared to handle these functions regardless of the type used.
10507 This example shows how the :ref:`va_arg <i_va_arg>` instruction and the
10508 variable argument handling intrinsic functions are used.
10510 .. code-block:: llvm
10512 ; This struct is different for every platform. For most platforms,
10513 ; it is merely an i8*.
10514 %struct.va_list = type { i8* }
10516 ; For Unix x86_64 platforms, va_list is the following struct:
10517 ; %struct.va_list = type { i32, i32, i8*, i8* }
10519 define i32 @test(i32 %X, ...) {
10520 ; Initialize variable argument processing
10521 %ap = alloca %struct.va_list
10522 %ap2 = bitcast %struct.va_list* %ap to i8*
10523 call void @llvm.va_start(i8* %ap2)
10525 ; Read a single integer argument
10526 %tmp = va_arg i8* %ap2, i32
10528 ; Demonstrate usage of llvm.va_copy and llvm.va_end
10530 %aq2 = bitcast i8** %aq to i8*
10531 call void @llvm.va_copy(i8* %aq2, i8* %ap2)
10532 call void @llvm.va_end(i8* %aq2)
10534 ; Stop processing of arguments.
10535 call void @llvm.va_end(i8* %ap2)
10539 declare void @llvm.va_start(i8*)
10540 declare void @llvm.va_copy(i8*, i8*)
10541 declare void @llvm.va_end(i8*)
10545 '``llvm.va_start``' Intrinsic
10546 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10553 declare void @llvm.va_start(i8* <arglist>)
10558 The '``llvm.va_start``' intrinsic initializes ``*<arglist>`` for
10559 subsequent use by ``va_arg``.
10564 The argument is a pointer to a ``va_list`` element to initialize.
10569 The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro
10570 available in C. In a target-dependent way, it initializes the
10571 ``va_list`` element to which the argument points, so that the next call
10572 to ``va_arg`` will produce the first variable argument passed to the
10573 function. Unlike the C ``va_start`` macro, this intrinsic does not need
10574 to know the last argument of the function as the compiler can figure
10577 '``llvm.va_end``' Intrinsic
10578 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
10585 declare void @llvm.va_end(i8* <arglist>)
10590 The '``llvm.va_end``' intrinsic destroys ``*<arglist>``, which has been
10591 initialized previously with ``llvm.va_start`` or ``llvm.va_copy``.
10596 The argument is a pointer to a ``va_list`` to destroy.
10601 The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro
10602 available in C. In a target-dependent way, it destroys the ``va_list``
10603 element to which the argument points. Calls to
10604 :ref:`llvm.va_start <int_va_start>` and
10605 :ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to
10610 '``llvm.va_copy``' Intrinsic
10611 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10618 declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
10623 The '``llvm.va_copy``' intrinsic copies the current argument position
10624 from the source argument list to the destination argument list.
10629 The first argument is a pointer to a ``va_list`` element to initialize.
10630 The second argument is a pointer to a ``va_list`` element to copy from.
10635 The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro
10636 available in C. In a target-dependent way, it copies the source
10637 ``va_list`` element into the destination ``va_list`` element. This
10638 intrinsic is necessary because the `` llvm.va_start`` intrinsic may be
10639 arbitrarily complex and require, for example, memory allocation.
10641 Accurate Garbage Collection Intrinsics
10642 --------------------------------------
10644 LLVM's support for `Accurate Garbage Collection <GarbageCollection.html>`_
10645 (GC) requires the frontend to generate code containing appropriate intrinsic
10646 calls and select an appropriate GC strategy which knows how to lower these
10647 intrinsics in a manner which is appropriate for the target collector.
10649 These intrinsics allow identification of :ref:`GC roots on the
10650 stack <int_gcroot>`, as well as garbage collector implementations that
10651 require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers.
10652 Frontends for type-safe garbage collected languages should generate
10653 these intrinsics to make use of the LLVM garbage collectors. For more
10654 details, see `Garbage Collection with LLVM <GarbageCollection.html>`_.
10656 Experimental Statepoint Intrinsics
10657 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10659 LLVM provides an second experimental set of intrinsics for describing garbage
10660 collection safepoints in compiled code. These intrinsics are an alternative
10661 to the ``llvm.gcroot`` intrinsics, but are compatible with the ones for
10662 :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. The
10663 differences in approach are covered in the `Garbage Collection with LLVM
10664 <GarbageCollection.html>`_ documentation. The intrinsics themselves are
10665 described in :doc:`Statepoints`.
10669 '``llvm.gcroot``' Intrinsic
10670 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
10677 declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
10682 The '``llvm.gcroot``' intrinsic declares the existence of a GC root to
10683 the code generator, and allows some metadata to be associated with it.
10688 The first argument specifies the address of a stack object that contains
10689 the root pointer. The second pointer (which must be either a constant or
10690 a global value address) contains the meta-data to be associated with the
10696 At runtime, a call to this intrinsic stores a null pointer into the
10697 "ptrloc" location. At compile-time, the code generator generates
10698 information to allow the runtime to find the pointer at GC safe points.
10699 The '``llvm.gcroot``' intrinsic may only be used in a function which
10700 :ref:`specifies a GC algorithm <gc>`.
10704 '``llvm.gcread``' Intrinsic
10705 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
10712 declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
10717 The '``llvm.gcread``' intrinsic identifies reads of references from heap
10718 locations, allowing garbage collector implementations that require read
10724 The second argument is the address to read from, which should be an
10725 address allocated from the garbage collector. The first object is a
10726 pointer to the start of the referenced object, if needed by the language
10727 runtime (otherwise null).
10732 The '``llvm.gcread``' intrinsic has the same semantics as a load
10733 instruction, but may be replaced with substantially more complex code by
10734 the garbage collector runtime, as needed. The '``llvm.gcread``'
10735 intrinsic may only be used in a function which :ref:`specifies a GC
10740 '``llvm.gcwrite``' Intrinsic
10741 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10748 declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
10753 The '``llvm.gcwrite``' intrinsic identifies writes of references to heap
10754 locations, allowing garbage collector implementations that require write
10755 barriers (such as generational or reference counting collectors).
10760 The first argument is the reference to store, the second is the start of
10761 the object to store it to, and the third is the address of the field of
10762 Obj to store to. If the runtime does not require a pointer to the
10763 object, Obj may be null.
10768 The '``llvm.gcwrite``' intrinsic has the same semantics as a store
10769 instruction, but may be replaced with substantially more complex code by
10770 the garbage collector runtime, as needed. The '``llvm.gcwrite``'
10771 intrinsic may only be used in a function which :ref:`specifies a GC
10774 Code Generator Intrinsics
10775 -------------------------
10777 These intrinsics are provided by LLVM to expose special features that
10778 may only be implemented with code generator support.
10780 '``llvm.returnaddress``' Intrinsic
10781 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10788 declare i8* @llvm.returnaddress(i32 <level>)
10793 The '``llvm.returnaddress``' intrinsic attempts to compute a
10794 target-specific value indicating the return address of the current
10795 function or one of its callers.
10800 The argument to this intrinsic indicates which function to return the
10801 address for. Zero indicates the calling function, one indicates its
10802 caller, etc. The argument is **required** to be a constant integer
10808 The '``llvm.returnaddress``' intrinsic either returns a pointer
10809 indicating the return address of the specified call frame, or zero if it
10810 cannot be identified. The value returned by this intrinsic is likely to
10811 be incorrect or 0 for arguments other than zero, so it should only be
10812 used for debugging purposes.
10814 Note that calling this intrinsic does not prevent function inlining or
10815 other aggressive transformations, so the value returned may not be that
10816 of the obvious source-language caller.
10818 '``llvm.addressofreturnaddress``' Intrinsic
10819 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10826 declare i8* @llvm.addressofreturnaddress()
10831 The '``llvm.addressofreturnaddress``' intrinsic returns a target-specific
10832 pointer to the place in the stack frame where the return address of the
10833 current function is stored.
10838 Note that calling this intrinsic does not prevent function inlining or
10839 other aggressive transformations, so the value returned may not be that
10840 of the obvious source-language caller.
10842 This intrinsic is only implemented for x86 and aarch64.
10844 '``llvm.sponentry``' Intrinsic
10845 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10852 declare i8* @llvm.sponentry()
10857 The '``llvm.sponentry``' intrinsic returns the stack pointer value at
10858 the entry of the current function calling this intrinsic.
10863 Note this intrinsic is only verified on AArch64.
10865 '``llvm.frameaddress``' Intrinsic
10866 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10873 declare i8* @llvm.frameaddress(i32 <level>)
10878 The '``llvm.frameaddress``' intrinsic attempts to return the
10879 target-specific frame pointer value for the specified stack frame.
10884 The argument to this intrinsic indicates which function to return the
10885 frame pointer for. Zero indicates the calling function, one indicates
10886 its caller, etc. The argument is **required** to be a constant integer
10892 The '``llvm.frameaddress``' intrinsic either returns a pointer
10893 indicating the frame address of the specified call frame, or zero if it
10894 cannot be identified. The value returned by this intrinsic is likely to
10895 be incorrect or 0 for arguments other than zero, so it should only be
10896 used for debugging purposes.
10898 Note that calling this intrinsic does not prevent function inlining or
10899 other aggressive transformations, so the value returned may not be that
10900 of the obvious source-language caller.
10902 '``llvm.localescape``' and '``llvm.localrecover``' Intrinsics
10903 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10910 declare void @llvm.localescape(...)
10911 declare i8* @llvm.localrecover(i8* %func, i8* %fp, i32 %idx)
10916 The '``llvm.localescape``' intrinsic escapes offsets of a collection of static
10917 allocas, and the '``llvm.localrecover``' intrinsic applies those offsets to a
10918 live frame pointer to recover the address of the allocation. The offset is
10919 computed during frame layout of the caller of ``llvm.localescape``.
10924 All arguments to '``llvm.localescape``' must be pointers to static allocas or
10925 casts of static allocas. Each function can only call '``llvm.localescape``'
10926 once, and it can only do so from the entry block.
10928 The ``func`` argument to '``llvm.localrecover``' must be a constant
10929 bitcasted pointer to a function defined in the current module. The code
10930 generator cannot determine the frame allocation offset of functions defined in
10933 The ``fp`` argument to '``llvm.localrecover``' must be a frame pointer of a
10934 call frame that is currently live. The return value of '``llvm.localaddress``'
10935 is one way to produce such a value, but various runtimes also expose a suitable
10936 pointer in platform-specific ways.
10938 The ``idx`` argument to '``llvm.localrecover``' indicates which alloca passed to
10939 '``llvm.localescape``' to recover. It is zero-indexed.
10944 These intrinsics allow a group of functions to share access to a set of local
10945 stack allocations of a one parent function. The parent function may call the
10946 '``llvm.localescape``' intrinsic once from the function entry block, and the
10947 child functions can use '``llvm.localrecover``' to access the escaped allocas.
10948 The '``llvm.localescape``' intrinsic blocks inlining, as inlining changes where
10949 the escaped allocas are allocated, which would break attempts to use
10950 '``llvm.localrecover``'.
10952 .. _int_read_register:
10953 .. _int_write_register:
10955 '``llvm.read_register``' and '``llvm.write_register``' Intrinsics
10956 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10963 declare i32 @llvm.read_register.i32(metadata)
10964 declare i64 @llvm.read_register.i64(metadata)
10965 declare void @llvm.write_register.i32(metadata, i32 @value)
10966 declare void @llvm.write_register.i64(metadata, i64 @value)
10972 The '``llvm.read_register``' and '``llvm.write_register``' intrinsics
10973 provides access to the named register. The register must be valid on
10974 the architecture being compiled to. The type needs to be compatible
10975 with the register being read.
10980 The '``llvm.read_register``' intrinsic returns the current value of the
10981 register, where possible. The '``llvm.write_register``' intrinsic sets
10982 the current value of the register, where possible.
10984 This is useful to implement named register global variables that need
10985 to always be mapped to a specific register, as is common practice on
10986 bare-metal programs including OS kernels.
10988 The compiler doesn't check for register availability or use of the used
10989 register in surrounding code, including inline assembly. Because of that,
10990 allocatable registers are not supported.
10992 Warning: So far it only works with the stack pointer on selected
10993 architectures (ARM, AArch64, PowerPC and x86_64). Significant amount of
10994 work is needed to support other registers and even more so, allocatable
10999 '``llvm.stacksave``' Intrinsic
11000 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11007 declare i8* @llvm.stacksave()
11012 The '``llvm.stacksave``' intrinsic is used to remember the current state
11013 of the function stack, for use with
11014 :ref:`llvm.stackrestore <int_stackrestore>`. This is useful for
11015 implementing language features like scoped automatic variable sized
11021 This intrinsic returns a opaque pointer value that can be passed to
11022 :ref:`llvm.stackrestore <int_stackrestore>`. When an
11023 ``llvm.stackrestore`` intrinsic is executed with a value saved from
11024 ``llvm.stacksave``, it effectively restores the state of the stack to
11025 the state it was in when the ``llvm.stacksave`` intrinsic executed. In
11026 practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that
11027 were allocated after the ``llvm.stacksave`` was executed.
11029 .. _int_stackrestore:
11031 '``llvm.stackrestore``' Intrinsic
11032 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11039 declare void @llvm.stackrestore(i8* %ptr)
11044 The '``llvm.stackrestore``' intrinsic is used to restore the state of
11045 the function stack to the state it was in when the corresponding
11046 :ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is
11047 useful for implementing language features like scoped automatic variable
11048 sized arrays in C99.
11053 See the description for :ref:`llvm.stacksave <int_stacksave>`.
11055 .. _int_get_dynamic_area_offset:
11057 '``llvm.get.dynamic.area.offset``' Intrinsic
11058 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11065 declare i32 @llvm.get.dynamic.area.offset.i32()
11066 declare i64 @llvm.get.dynamic.area.offset.i64()
11071 The '``llvm.get.dynamic.area.offset.*``' intrinsic family is used to
11072 get the offset from native stack pointer to the address of the most
11073 recent dynamic alloca on the caller's stack. These intrinsics are
11074 intendend for use in combination with
11075 :ref:`llvm.stacksave <int_stacksave>` to get a
11076 pointer to the most recent dynamic alloca. This is useful, for example,
11077 for AddressSanitizer's stack unpoisoning routines.
11082 These intrinsics return a non-negative integer value that can be used to
11083 get the address of the most recent dynamic alloca, allocated by :ref:`alloca <i_alloca>`
11084 on the caller's stack. In particular, for targets where stack grows downwards,
11085 adding this offset to the native stack pointer would get the address of the most
11086 recent dynamic alloca. For targets where stack grows upwards, the situation is a bit more
11087 complicated, because subtracting this value from stack pointer would get the address
11088 one past the end of the most recent dynamic alloca.
11090 Although for most targets `llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>`
11091 returns just a zero, for others, such as PowerPC and PowerPC64, it returns a
11092 compile-time-known constant value.
11094 The return value type of :ref:`llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>`
11095 must match the target's default address space's (address space 0) pointer type.
11097 '``llvm.prefetch``' Intrinsic
11098 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11105 declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
11110 The '``llvm.prefetch``' intrinsic is a hint to the code generator to
11111 insert a prefetch instruction if supported; otherwise, it is a noop.
11112 Prefetches have no effect on the behavior of the program but can change
11113 its performance characteristics.
11118 ``address`` is the address to be prefetched, ``rw`` is the specifier
11119 determining if the fetch should be for a read (0) or write (1), and
11120 ``locality`` is a temporal locality specifier ranging from (0) - no
11121 locality, to (3) - extremely local keep in cache. The ``cache type``
11122 specifies whether the prefetch is performed on the data (1) or
11123 instruction (0) cache. The ``rw``, ``locality`` and ``cache type``
11124 arguments must be constant integers.
11129 This intrinsic does not modify the behavior of the program. In
11130 particular, prefetches cannot trap and do not produce a value. On
11131 targets that support this intrinsic, the prefetch can provide hints to
11132 the processor cache for better performance.
11134 '``llvm.pcmarker``' Intrinsic
11135 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11142 declare void @llvm.pcmarker(i32 <id>)
11147 The '``llvm.pcmarker``' intrinsic is a method to export a Program
11148 Counter (PC) in a region of code to simulators and other tools. The
11149 method is target specific, but it is expected that the marker will use
11150 exported symbols to transmit the PC of the marker. The marker makes no
11151 guarantees that it will remain with any specific instruction after
11152 optimizations. It is possible that the presence of a marker will inhibit
11153 optimizations. The intended use is to be inserted after optimizations to
11154 allow correlations of simulation runs.
11159 ``id`` is a numerical id identifying the marker.
11164 This intrinsic does not modify the behavior of the program. Backends
11165 that do not support this intrinsic may ignore it.
11167 '``llvm.readcyclecounter``' Intrinsic
11168 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11175 declare i64 @llvm.readcyclecounter()
11180 The '``llvm.readcyclecounter``' intrinsic provides access to the cycle
11181 counter register (or similar low latency, high accuracy clocks) on those
11182 targets that support it. On X86, it should map to RDTSC. On Alpha, it
11183 should map to RPCC. As the backing counters overflow quickly (on the
11184 order of 9 seconds on alpha), this should only be used for small
11190 When directly supported, reading the cycle counter should not modify any
11191 memory. Implementations are allowed to either return a application
11192 specific value or a system wide value. On backends without support, this
11193 is lowered to a constant 0.
11195 Note that runtime support may be conditional on the privilege-level code is
11196 running at and the host platform.
11198 '``llvm.clear_cache``' Intrinsic
11199 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11206 declare void @llvm.clear_cache(i8*, i8*)
11211 The '``llvm.clear_cache``' intrinsic ensures visibility of modifications
11212 in the specified range to the execution unit of the processor. On
11213 targets with non-unified instruction and data cache, the implementation
11214 flushes the instruction cache.
11219 On platforms with coherent instruction and data caches (e.g. x86), this
11220 intrinsic is a nop. On platforms with non-coherent instruction and data
11221 cache (e.g. ARM, MIPS), the intrinsic is lowered either to appropriate
11222 instructions or a system call, if cache flushing requires special
11225 The default behavior is to emit a call to ``__clear_cache`` from the run
11228 This instrinsic does *not* empty the instruction pipeline. Modifications
11229 of the current function are outside the scope of the intrinsic.
11231 '``llvm.instrprof.increment``' Intrinsic
11232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11239 declare void @llvm.instrprof.increment(i8* <name>, i64 <hash>,
11240 i32 <num-counters>, i32 <index>)
11245 The '``llvm.instrprof.increment``' intrinsic can be emitted by a
11246 frontend for use with instrumentation based profiling. These will be
11247 lowered by the ``-instrprof`` pass to generate execution counts of a
11248 program at runtime.
11253 The first argument is a pointer to a global variable containing the
11254 name of the entity being instrumented. This should generally be the
11255 (mangled) function name for a set of counters.
11257 The second argument is a hash value that can be used by the consumer
11258 of the profile data to detect changes to the instrumented source, and
11259 the third is the number of counters associated with ``name``. It is an
11260 error if ``hash`` or ``num-counters`` differ between two instances of
11261 ``instrprof.increment`` that refer to the same name.
11263 The last argument refers to which of the counters for ``name`` should
11264 be incremented. It should be a value between 0 and ``num-counters``.
11269 This intrinsic represents an increment of a profiling counter. It will
11270 cause the ``-instrprof`` pass to generate the appropriate data
11271 structures and the code to increment the appropriate value, in a
11272 format that can be written out by a compiler runtime and consumed via
11273 the ``llvm-profdata`` tool.
11275 '``llvm.instrprof.increment.step``' Intrinsic
11276 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11283 declare void @llvm.instrprof.increment.step(i8* <name>, i64 <hash>,
11284 i32 <num-counters>,
11285 i32 <index>, i64 <step>)
11290 The '``llvm.instrprof.increment.step``' intrinsic is an extension to
11291 the '``llvm.instrprof.increment``' intrinsic with an additional fifth
11292 argument to specify the step of the increment.
11296 The first four arguments are the same as '``llvm.instrprof.increment``'
11299 The last argument specifies the value of the increment of the counter variable.
11303 See description of '``llvm.instrprof.increment``' instrinsic.
11306 '``llvm.instrprof.value.profile``' Intrinsic
11307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11314 declare void @llvm.instrprof.value.profile(i8* <name>, i64 <hash>,
11315 i64 <value>, i32 <value_kind>,
11321 The '``llvm.instrprof.value.profile``' intrinsic can be emitted by a
11322 frontend for use with instrumentation based profiling. This will be
11323 lowered by the ``-instrprof`` pass to find out the target values,
11324 instrumented expressions take in a program at runtime.
11329 The first argument is a pointer to a global variable containing the
11330 name of the entity being instrumented. ``name`` should generally be the
11331 (mangled) function name for a set of counters.
11333 The second argument is a hash value that can be used by the consumer
11334 of the profile data to detect changes to the instrumented source. It
11335 is an error if ``hash`` differs between two instances of
11336 ``llvm.instrprof.*`` that refer to the same name.
11338 The third argument is the value of the expression being profiled. The profiled
11339 expression's value should be representable as an unsigned 64-bit value. The
11340 fourth argument represents the kind of value profiling that is being done. The
11341 supported value profiling kinds are enumerated through the
11342 ``InstrProfValueKind`` type declared in the
11343 ``<include/llvm/ProfileData/InstrProf.h>`` header file. The last argument is the
11344 index of the instrumented expression within ``name``. It should be >= 0.
11349 This intrinsic represents the point where a call to a runtime routine
11350 should be inserted for value profiling of target expressions. ``-instrprof``
11351 pass will generate the appropriate data structures and replace the
11352 ``llvm.instrprof.value.profile`` intrinsic with the call to the profile
11353 runtime library with proper arguments.
11355 '``llvm.thread.pointer``' Intrinsic
11356 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11363 declare i8* @llvm.thread.pointer()
11368 The '``llvm.thread.pointer``' intrinsic returns the value of the thread
11374 The '``llvm.thread.pointer``' intrinsic returns a pointer to the TLS area
11375 for the current thread. The exact semantics of this value are target
11376 specific: it may point to the start of TLS area, to the end, or somewhere
11377 in the middle. Depending on the target, this intrinsic may read a register,
11378 call a helper function, read from an alternate memory space, or perform
11379 other operations necessary to locate the TLS area. Not all targets support
11382 Standard C Library Intrinsics
11383 -----------------------------
11385 LLVM provides intrinsics for a few important standard C library
11386 functions. These intrinsics allow source-language front-ends to pass
11387 information about the alignment of the pointer arguments to the code
11388 generator, providing opportunity for more efficient code generation.
11392 '``llvm.memcpy``' Intrinsic
11393 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
11398 This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any
11399 integer bit width and for different address spaces. Not all targets
11400 support all bit widths however.
11404 declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
11405 i32 <len>, i1 <isvolatile>)
11406 declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
11407 i64 <len>, i1 <isvolatile>)
11412 The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
11413 source location to the destination location.
11415 Note that, unlike the standard libc function, the ``llvm.memcpy.*``
11416 intrinsics do not return a value, takes extra isvolatile
11417 arguments and the pointers can be in specified address spaces.
11422 The first argument is a pointer to the destination, the second is a
11423 pointer to the source. The third argument is an integer argument
11424 specifying the number of bytes to copy, and the fourth is a
11425 boolean indicating a volatile access.
11427 The :ref:`align <attr_align>` parameter attribute can be provided
11428 for the first and second arguments.
11430 If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is
11431 a :ref:`volatile operation <volatile>`. The detailed access behavior is not
11432 very cleanly specified and it is unwise to depend on it.
11437 The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
11438 source location to the destination location, which are not allowed to
11439 overlap. It copies "len" bytes of memory over. If the argument is known
11440 to be aligned to some boundary, this can be specified as an attribute on
11443 If "len" is 0, the pointers may be NULL or dangling. However, they must still
11444 be appropriately aligned.
11448 '``llvm.memmove``' Intrinsic
11449 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11454 This is an overloaded intrinsic. You can use llvm.memmove on any integer
11455 bit width and for different address space. Not all targets support all
11456 bit widths however.
11460 declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
11461 i32 <len>, i1 <isvolatile>)
11462 declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
11463 i64 <len>, i1 <isvolatile>)
11468 The '``llvm.memmove.*``' intrinsics move a block of memory from the
11469 source location to the destination location. It is similar to the
11470 '``llvm.memcpy``' intrinsic but allows the two memory locations to
11473 Note that, unlike the standard libc function, the ``llvm.memmove.*``
11474 intrinsics do not return a value, takes an extra isvolatile
11475 argument and the pointers can be in specified address spaces.
11480 The first argument is a pointer to the destination, the second is a
11481 pointer to the source. The third argument is an integer argument
11482 specifying the number of bytes to copy, and the fourth is a
11483 boolean indicating a volatile access.
11485 The :ref:`align <attr_align>` parameter attribute can be provided
11486 for the first and second arguments.
11488 If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call
11489 is a :ref:`volatile operation <volatile>`. The detailed access behavior is
11490 not very cleanly specified and it is unwise to depend on it.
11495 The '``llvm.memmove.*``' intrinsics copy a block of memory from the
11496 source location to the destination location, which may overlap. It
11497 copies "len" bytes of memory over. If the argument is known to be
11498 aligned to some boundary, this can be specified as an attribute on
11501 If "len" is 0, the pointers may be NULL or dangling. However, they must still
11502 be appropriately aligned.
11506 '``llvm.memset.*``' Intrinsics
11507 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11512 This is an overloaded intrinsic. You can use llvm.memset on any integer
11513 bit width and for different address spaces. However, not all targets
11514 support all bit widths.
11518 declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>,
11519 i32 <len>, i1 <isvolatile>)
11520 declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>,
11521 i64 <len>, i1 <isvolatile>)
11526 The '``llvm.memset.*``' intrinsics fill a block of memory with a
11527 particular byte value.
11529 Note that, unlike the standard libc function, the ``llvm.memset``
11530 intrinsic does not return a value and takes an extra volatile
11531 argument. Also, the destination can be in an arbitrary address space.
11536 The first argument is a pointer to the destination to fill, the second
11537 is the byte value with which to fill it, the third argument is an
11538 integer argument specifying the number of bytes to fill, and the fourth
11539 is a boolean indicating a volatile access.
11541 The :ref:`align <attr_align>` parameter attribute can be provided
11542 for the first arguments.
11544 If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is
11545 a :ref:`volatile operation <volatile>`. The detailed access behavior is not
11546 very cleanly specified and it is unwise to depend on it.
11551 The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting
11552 at the destination location. If the argument is known to be
11553 aligned to some boundary, this can be specified as an attribute on
11556 If "len" is 0, the pointers may be NULL or dangling. However, they must still
11557 be appropriately aligned.
11559 '``llvm.sqrt.*``' Intrinsic
11560 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
11565 This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any
11566 floating-point or vector of floating-point type. Not all targets support
11571 declare float @llvm.sqrt.f32(float %Val)
11572 declare double @llvm.sqrt.f64(double %Val)
11573 declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val)
11574 declare fp128 @llvm.sqrt.f128(fp128 %Val)
11575 declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
11580 The '``llvm.sqrt``' intrinsics return the square root of the specified value.
11585 The argument and return value are floating-point numbers of the same type.
11590 Return the same value as a corresponding libm '``sqrt``' function but without
11591 trapping or setting ``errno``. For types specified by IEEE-754, the result
11592 matches a conforming libm implementation.
11594 When specified with the fast-math-flag 'afn', the result may be approximated
11595 using a less accurate calculation.
11597 '``llvm.powi.*``' Intrinsic
11598 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
11603 This is an overloaded intrinsic. You can use ``llvm.powi`` on any
11604 floating-point or vector of floating-point type. Not all targets support
11609 declare float @llvm.powi.f32(float %Val, i32 %power)
11610 declare double @llvm.powi.f64(double %Val, i32 %power)
11611 declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power)
11612 declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power)
11613 declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power)
11618 The '``llvm.powi.*``' intrinsics return the first operand raised to the
11619 specified (positive or negative) power. The order of evaluation of
11620 multiplications is not defined. When a vector of floating-point type is
11621 used, the second argument remains a scalar integer value.
11626 The second argument is an integer power, and the first is a value to
11627 raise to that power.
11632 This function returns the first value raised to the second power with an
11633 unspecified sequence of rounding operations.
11635 '``llvm.sin.*``' Intrinsic
11636 ^^^^^^^^^^^^^^^^^^^^^^^^^^
11641 This is an overloaded intrinsic. You can use ``llvm.sin`` on any
11642 floating-point or vector of floating-point type. Not all targets support
11647 declare float @llvm.sin.f32(float %Val)
11648 declare double @llvm.sin.f64(double %Val)
11649 declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val)
11650 declare fp128 @llvm.sin.f128(fp128 %Val)
11651 declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val)
11656 The '``llvm.sin.*``' intrinsics return the sine of the operand.
11661 The argument and return value are floating-point numbers of the same type.
11666 Return the same value as a corresponding libm '``sin``' function but without
11667 trapping or setting ``errno``.
11669 When specified with the fast-math-flag 'afn', the result may be approximated
11670 using a less accurate calculation.
11672 '``llvm.cos.*``' Intrinsic
11673 ^^^^^^^^^^^^^^^^^^^^^^^^^^
11678 This is an overloaded intrinsic. You can use ``llvm.cos`` on any
11679 floating-point or vector of floating-point type. Not all targets support
11684 declare float @llvm.cos.f32(float %Val)
11685 declare double @llvm.cos.f64(double %Val)
11686 declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val)
11687 declare fp128 @llvm.cos.f128(fp128 %Val)
11688 declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val)
11693 The '``llvm.cos.*``' intrinsics return the cosine of the operand.
11698 The argument and return value are floating-point numbers of the same type.
11703 Return the same value as a corresponding libm '``cos``' function but without
11704 trapping or setting ``errno``.
11706 When specified with the fast-math-flag 'afn', the result may be approximated
11707 using a less accurate calculation.
11709 '``llvm.pow.*``' Intrinsic
11710 ^^^^^^^^^^^^^^^^^^^^^^^^^^
11715 This is an overloaded intrinsic. You can use ``llvm.pow`` on any
11716 floating-point or vector of floating-point type. Not all targets support
11721 declare float @llvm.pow.f32(float %Val, float %Power)
11722 declare double @llvm.pow.f64(double %Val, double %Power)
11723 declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power)
11724 declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power)
11725 declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power)
11730 The '``llvm.pow.*``' intrinsics return the first operand raised to the
11731 specified (positive or negative) power.
11736 The arguments and return value are floating-point numbers of the same type.
11741 Return the same value as a corresponding libm '``pow``' function but without
11742 trapping or setting ``errno``.
11744 When specified with the fast-math-flag 'afn', the result may be approximated
11745 using a less accurate calculation.
11747 '``llvm.exp.*``' Intrinsic
11748 ^^^^^^^^^^^^^^^^^^^^^^^^^^
11753 This is an overloaded intrinsic. You can use ``llvm.exp`` on any
11754 floating-point or vector of floating-point type. Not all targets support
11759 declare float @llvm.exp.f32(float %Val)
11760 declare double @llvm.exp.f64(double %Val)
11761 declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val)
11762 declare fp128 @llvm.exp.f128(fp128 %Val)
11763 declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val)
11768 The '``llvm.exp.*``' intrinsics compute the base-e exponential of the specified
11774 The argument and return value are floating-point numbers of the same type.
11779 Return the same value as a corresponding libm '``exp``' function but without
11780 trapping or setting ``errno``.
11782 When specified with the fast-math-flag 'afn', the result may be approximated
11783 using a less accurate calculation.
11785 '``llvm.exp2.*``' Intrinsic
11786 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
11791 This is an overloaded intrinsic. You can use ``llvm.exp2`` on any
11792 floating-point or vector of floating-point type. Not all targets support
11797 declare float @llvm.exp2.f32(float %Val)
11798 declare double @llvm.exp2.f64(double %Val)
11799 declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val)
11800 declare fp128 @llvm.exp2.f128(fp128 %Val)
11801 declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val)
11806 The '``llvm.exp2.*``' intrinsics compute the base-2 exponential of the
11812 The argument and return value are floating-point numbers of the same type.
11817 Return the same value as a corresponding libm '``exp2``' function but without
11818 trapping or setting ``errno``.
11820 When specified with the fast-math-flag 'afn', the result may be approximated
11821 using a less accurate calculation.
11823 '``llvm.log.*``' Intrinsic
11824 ^^^^^^^^^^^^^^^^^^^^^^^^^^
11829 This is an overloaded intrinsic. You can use ``llvm.log`` on any
11830 floating-point or vector of floating-point type. Not all targets support
11835 declare float @llvm.log.f32(float %Val)
11836 declare double @llvm.log.f64(double %Val)
11837 declare x86_fp80 @llvm.log.f80(x86_fp80 %Val)
11838 declare fp128 @llvm.log.f128(fp128 %Val)
11839 declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val)
11844 The '``llvm.log.*``' intrinsics compute the base-e logarithm of the specified
11850 The argument and return value are floating-point numbers of the same type.
11855 Return the same value as a corresponding libm '``log``' function but without
11856 trapping or setting ``errno``.
11858 When specified with the fast-math-flag 'afn', the result may be approximated
11859 using a less accurate calculation.
11861 '``llvm.log10.*``' Intrinsic
11862 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11867 This is an overloaded intrinsic. You can use ``llvm.log10`` on any
11868 floating-point or vector of floating-point type. Not all targets support
11873 declare float @llvm.log10.f32(float %Val)
11874 declare double @llvm.log10.f64(double %Val)
11875 declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val)
11876 declare fp128 @llvm.log10.f128(fp128 %Val)
11877 declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val)
11882 The '``llvm.log10.*``' intrinsics compute the base-10 logarithm of the
11888 The argument and return value are floating-point numbers of the same type.
11893 Return the same value as a corresponding libm '``log10``' function but without
11894 trapping or setting ``errno``.
11896 When specified with the fast-math-flag 'afn', the result may be approximated
11897 using a less accurate calculation.
11899 '``llvm.log2.*``' Intrinsic
11900 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
11905 This is an overloaded intrinsic. You can use ``llvm.log2`` on any
11906 floating-point or vector of floating-point type. Not all targets support
11911 declare float @llvm.log2.f32(float %Val)
11912 declare double @llvm.log2.f64(double %Val)
11913 declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val)
11914 declare fp128 @llvm.log2.f128(fp128 %Val)
11915 declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val)
11920 The '``llvm.log2.*``' intrinsics compute the base-2 logarithm of the specified
11926 The argument and return value are floating-point numbers of the same type.
11931 Return the same value as a corresponding libm '``log2``' function but without
11932 trapping or setting ``errno``.
11934 When specified with the fast-math-flag 'afn', the result may be approximated
11935 using a less accurate calculation.
11937 '``llvm.fma.*``' Intrinsic
11938 ^^^^^^^^^^^^^^^^^^^^^^^^^^
11943 This is an overloaded intrinsic. You can use ``llvm.fma`` on any
11944 floating-point or vector of floating-point type. Not all targets support
11949 declare float @llvm.fma.f32(float %a, float %b, float %c)
11950 declare double @llvm.fma.f64(double %a, double %b, double %c)
11951 declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
11952 declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
11953 declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
11958 The '``llvm.fma.*``' intrinsics perform the fused multiply-add operation.
11963 The arguments and return value are floating-point numbers of the same type.
11968 Return the same value as a corresponding libm '``fma``' function but without
11969 trapping or setting ``errno``.
11971 When specified with the fast-math-flag 'afn', the result may be approximated
11972 using a less accurate calculation.
11974 '``llvm.fabs.*``' Intrinsic
11975 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
11980 This is an overloaded intrinsic. You can use ``llvm.fabs`` on any
11981 floating-point or vector of floating-point type. Not all targets support
11986 declare float @llvm.fabs.f32(float %Val)
11987 declare double @llvm.fabs.f64(double %Val)
11988 declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val)
11989 declare fp128 @llvm.fabs.f128(fp128 %Val)
11990 declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val)
11995 The '``llvm.fabs.*``' intrinsics return the absolute value of the
12001 The argument and return value are floating-point numbers of the same
12007 This function returns the same values as the libm ``fabs`` functions
12008 would, and handles error conditions in the same way.
12010 '``llvm.minnum.*``' Intrinsic
12011 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12016 This is an overloaded intrinsic. You can use ``llvm.minnum`` on any
12017 floating-point or vector of floating-point type. Not all targets support
12022 declare float @llvm.minnum.f32(float %Val0, float %Val1)
12023 declare double @llvm.minnum.f64(double %Val0, double %Val1)
12024 declare x86_fp80 @llvm.minnum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
12025 declare fp128 @llvm.minnum.f128(fp128 %Val0, fp128 %Val1)
12026 declare ppc_fp128 @llvm.minnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
12031 The '``llvm.minnum.*``' intrinsics return the minimum of the two
12038 The arguments and return value are floating-point numbers of the same
12044 Follows the IEEE-754 semantics for minNum, except for handling of
12045 signaling NaNs. This match's the behavior of libm's fmin.
12047 If either operand is a NaN, returns the other non-NaN operand. Returns
12048 NaN only if both operands are NaN. The returned NaN is always
12049 quiet. If the operands compare equal, returns a value that compares
12050 equal to both operands. This means that fmin(+/-0.0, +/-0.0) could
12051 return either -0.0 or 0.0.
12053 Unlike the IEEE-754 2008 behavior, this does not distinguish between
12054 signaling and quiet NaN inputs. If a target's implementation follows
12055 the standard and returns a quiet NaN if either input is a signaling
12056 NaN, the intrinsic lowering is responsible for quieting the inputs to
12057 correctly return the non-NaN input (e.g. by using the equivalent of
12058 ``llvm.canonicalize``).
12061 '``llvm.maxnum.*``' Intrinsic
12062 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12067 This is an overloaded intrinsic. You can use ``llvm.maxnum`` on any
12068 floating-point or vector of floating-point type. Not all targets support
12073 declare float @llvm.maxnum.f32(float %Val0, float %Val1l)
12074 declare double @llvm.maxnum.f64(double %Val0, double %Val1)
12075 declare x86_fp80 @llvm.maxnum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
12076 declare fp128 @llvm.maxnum.f128(fp128 %Val0, fp128 %Val1)
12077 declare ppc_fp128 @llvm.maxnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
12082 The '``llvm.maxnum.*``' intrinsics return the maximum of the two
12089 The arguments and return value are floating-point numbers of the same
12094 Follows the IEEE-754 semantics for maxNum except for the handling of
12095 signaling NaNs. This matches the behavior of libm's fmax.
12097 If either operand is a NaN, returns the other non-NaN operand. Returns
12098 NaN only if both operands are NaN. The returned NaN is always
12099 quiet. If the operands compare equal, returns a value that compares
12100 equal to both operands. This means that fmax(+/-0.0, +/-0.0) could
12101 return either -0.0 or 0.0.
12103 Unlike the IEEE-754 2008 behavior, this does not distinguish between
12104 signaling and quiet NaN inputs. If a target's implementation follows
12105 the standard and returns a quiet NaN if either input is a signaling
12106 NaN, the intrinsic lowering is responsible for quieting the inputs to
12107 correctly return the non-NaN input (e.g. by using the equivalent of
12108 ``llvm.canonicalize``).
12110 '``llvm.minimum.*``' Intrinsic
12111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12116 This is an overloaded intrinsic. You can use ``llvm.minimum`` on any
12117 floating-point or vector of floating-point type. Not all targets support
12122 declare float @llvm.minimum.f32(float %Val0, float %Val1)
12123 declare double @llvm.minimum.f64(double %Val0, double %Val1)
12124 declare x86_fp80 @llvm.minimum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
12125 declare fp128 @llvm.minimum.f128(fp128 %Val0, fp128 %Val1)
12126 declare ppc_fp128 @llvm.minimum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
12131 The '``llvm.minimum.*``' intrinsics return the minimum of the two
12132 arguments, propagating NaNs and treating -0.0 as less than +0.0.
12138 The arguments and return value are floating-point numbers of the same
12143 If either operand is a NaN, returns NaN. Otherwise returns the lesser
12144 of the two arguments. -0.0 is considered to be less than +0.0 for this
12145 intrinsic. Note that these are the semantics specified in the draft of
12148 '``llvm.maximum.*``' Intrinsic
12149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12154 This is an overloaded intrinsic. You can use ``llvm.maximum`` on any
12155 floating-point or vector of floating-point type. Not all targets support
12160 declare float @llvm.maximum.f32(float %Val0, float %Val1)
12161 declare double @llvm.maximum.f64(double %Val0, double %Val1)
12162 declare x86_fp80 @llvm.maximum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
12163 declare fp128 @llvm.maximum.f128(fp128 %Val0, fp128 %Val1)
12164 declare ppc_fp128 @llvm.maximum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
12169 The '``llvm.maximum.*``' intrinsics return the maximum of the two
12170 arguments, propagating NaNs and treating -0.0 as less than +0.0.
12176 The arguments and return value are floating-point numbers of the same
12181 If either operand is a NaN, returns NaN. Otherwise returns the greater
12182 of the two arguments. -0.0 is considered to be less than +0.0 for this
12183 intrinsic. Note that these are the semantics specified in the draft of
12186 '``llvm.copysign.*``' Intrinsic
12187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12192 This is an overloaded intrinsic. You can use ``llvm.copysign`` on any
12193 floating-point or vector of floating-point type. Not all targets support
12198 declare float @llvm.copysign.f32(float %Mag, float %Sgn)
12199 declare double @llvm.copysign.f64(double %Mag, double %Sgn)
12200 declare x86_fp80 @llvm.copysign.f80(x86_fp80 %Mag, x86_fp80 %Sgn)
12201 declare fp128 @llvm.copysign.f128(fp128 %Mag, fp128 %Sgn)
12202 declare ppc_fp128 @llvm.copysign.ppcf128(ppc_fp128 %Mag, ppc_fp128 %Sgn)
12207 The '``llvm.copysign.*``' intrinsics return a value with the magnitude of the
12208 first operand and the sign of the second operand.
12213 The arguments and return value are floating-point numbers of the same
12219 This function returns the same values as the libm ``copysign``
12220 functions would, and handles error conditions in the same way.
12222 '``llvm.floor.*``' Intrinsic
12223 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12228 This is an overloaded intrinsic. You can use ``llvm.floor`` on any
12229 floating-point or vector of floating-point type. Not all targets support
12234 declare float @llvm.floor.f32(float %Val)
12235 declare double @llvm.floor.f64(double %Val)
12236 declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val)
12237 declare fp128 @llvm.floor.f128(fp128 %Val)
12238 declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val)
12243 The '``llvm.floor.*``' intrinsics return the floor of the operand.
12248 The argument and return value are floating-point numbers of the same
12254 This function returns the same values as the libm ``floor`` functions
12255 would, and handles error conditions in the same way.
12257 '``llvm.ceil.*``' Intrinsic
12258 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
12263 This is an overloaded intrinsic. You can use ``llvm.ceil`` on any
12264 floating-point or vector of floating-point type. Not all targets support
12269 declare float @llvm.ceil.f32(float %Val)
12270 declare double @llvm.ceil.f64(double %Val)
12271 declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val)
12272 declare fp128 @llvm.ceil.f128(fp128 %Val)
12273 declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val)
12278 The '``llvm.ceil.*``' intrinsics return the ceiling of the operand.
12283 The argument and return value are floating-point numbers of the same
12289 This function returns the same values as the libm ``ceil`` functions
12290 would, and handles error conditions in the same way.
12292 '``llvm.trunc.*``' Intrinsic
12293 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12298 This is an overloaded intrinsic. You can use ``llvm.trunc`` on any
12299 floating-point or vector of floating-point type. Not all targets support
12304 declare float @llvm.trunc.f32(float %Val)
12305 declare double @llvm.trunc.f64(double %Val)
12306 declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val)
12307 declare fp128 @llvm.trunc.f128(fp128 %Val)
12308 declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val)
12313 The '``llvm.trunc.*``' intrinsics returns the operand rounded to the
12314 nearest integer not larger in magnitude than the operand.
12319 The argument and return value are floating-point numbers of the same
12325 This function returns the same values as the libm ``trunc`` functions
12326 would, and handles error conditions in the same way.
12328 '``llvm.rint.*``' Intrinsic
12329 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
12334 This is an overloaded intrinsic. You can use ``llvm.rint`` on any
12335 floating-point or vector of floating-point type. Not all targets support
12340 declare float @llvm.rint.f32(float %Val)
12341 declare double @llvm.rint.f64(double %Val)
12342 declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val)
12343 declare fp128 @llvm.rint.f128(fp128 %Val)
12344 declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val)
12349 The '``llvm.rint.*``' intrinsics returns the operand rounded to the
12350 nearest integer. It may raise an inexact floating-point exception if the
12351 operand isn't an integer.
12356 The argument and return value are floating-point numbers of the same
12362 This function returns the same values as the libm ``rint`` functions
12363 would, and handles error conditions in the same way.
12365 '``llvm.nearbyint.*``' Intrinsic
12366 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12371 This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any
12372 floating-point or vector of floating-point type. Not all targets support
12377 declare float @llvm.nearbyint.f32(float %Val)
12378 declare double @llvm.nearbyint.f64(double %Val)
12379 declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val)
12380 declare fp128 @llvm.nearbyint.f128(fp128 %Val)
12381 declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val)
12386 The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the
12392 The argument and return value are floating-point numbers of the same
12398 This function returns the same values as the libm ``nearbyint``
12399 functions would, and handles error conditions in the same way.
12401 '``llvm.round.*``' Intrinsic
12402 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12407 This is an overloaded intrinsic. You can use ``llvm.round`` on any
12408 floating-point or vector of floating-point type. Not all targets support
12413 declare float @llvm.round.f32(float %Val)
12414 declare double @llvm.round.f64(double %Val)
12415 declare x86_fp80 @llvm.round.f80(x86_fp80 %Val)
12416 declare fp128 @llvm.round.f128(fp128 %Val)
12417 declare ppc_fp128 @llvm.round.ppcf128(ppc_fp128 %Val)
12422 The '``llvm.round.*``' intrinsics returns the operand rounded to the
12428 The argument and return value are floating-point numbers of the same
12434 This function returns the same values as the libm ``round``
12435 functions would, and handles error conditions in the same way.
12437 '``llvm.lround.*``' Intrinsic
12438 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12443 This is an overloaded intrinsic. You can use ``llvm.lround`` on any
12444 floating-point type. Not all targets support all types however.
12448 declare i32 @llvm.lround.i32.f32(float %Val)
12449 declare i32 @llvm.lround.i32.f64(double %Val)
12450 declare i32 @llvm.lround.i32.f80(float %Val)
12451 declare i32 @llvm.lround.i32.f128(double %Val)
12452 declare i32 @llvm.lround.i32.ppcf128(double %Val)
12454 declare i64 @llvm.lround.i64.f32(float %Val)
12455 declare i64 @llvm.lround.i64.f64(double %Val)
12456 declare i64 @llvm.lround.i64.f80(float %Val)
12457 declare i64 @llvm.lround.i64.f128(double %Val)
12458 declare i64 @llvm.lround.i64.ppcf128(double %Val)
12463 The '``llvm.lround.*``' intrinsics returns the operand rounded to the
12469 The argument is a floating-point number and return is an integer type.
12474 This function returns the same values as the libm ``lround``
12475 functions would, but without setting errno.
12477 '``llvm.llround.*``' Intrinsic
12478 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12483 This is an overloaded intrinsic. You can use ``llvm.llround`` on any
12484 floating-point type. Not all targets support all types however.
12488 declare i64 @llvm.lround.i64.f32(float %Val)
12489 declare i64 @llvm.lround.i64.f64(double %Val)
12490 declare i64 @llvm.lround.i64.f80(float %Val)
12491 declare i64 @llvm.lround.i64.f128(double %Val)
12492 declare i64 @llvm.lround.i64.ppcf128(double %Val)
12497 The '``llvm.llround.*``' intrinsics returns the operand rounded to the
12503 The argument is a floating-point number and return is an integer type.
12508 This function returns the same values as the libm ``llround``
12509 functions would, but without setting errno.
12511 '``llvm.lrint.*``' Intrinsic
12512 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12517 This is an overloaded intrinsic. You can use ``llvm.lrint`` on any
12518 floating-point type. Not all targets support all types however.
12522 declare i32 @llvm.lrint.i32.f32(float %Val)
12523 declare i32 @llvm.lrint.i32.f64(double %Val)
12524 declare i32 @llvm.lrint.i32.f80(float %Val)
12525 declare i32 @llvm.lrint.i32.f128(double %Val)
12526 declare i32 @llvm.lrint.i32.ppcf128(double %Val)
12528 declare i64 @llvm.lrint.i64.f32(float %Val)
12529 declare i64 @llvm.lrint.i64.f64(double %Val)
12530 declare i64 @llvm.lrint.i64.f80(float %Val)
12531 declare i64 @llvm.lrint.i64.f128(double %Val)
12532 declare i64 @llvm.lrint.i64.ppcf128(double %Val)
12537 The '``llvm.lrint.*``' intrinsics returns the operand rounded to the
12543 The argument is a floating-point number and return is an integer type.
12548 This function returns the same values as the libm ``lrint``
12549 functions would, but without setting errno.
12551 '``llvm.llrint.*``' Intrinsic
12552 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12557 This is an overloaded intrinsic. You can use ``llvm.llrint`` on any
12558 floating-point type. Not all targets support all types however.
12562 declare i64 @llvm.llrint.i64.f32(float %Val)
12563 declare i64 @llvm.llrint.i64.f64(double %Val)
12564 declare i64 @llvm.llrint.i64.f80(float %Val)
12565 declare i64 @llvm.llrint.i64.f128(double %Val)
12566 declare i64 @llvm.llrint.i64.ppcf128(double %Val)
12571 The '``llvm.llrint.*``' intrinsics returns the operand rounded to the
12577 The argument is a floating-point number and return is an integer type.
12582 This function returns the same values as the libm ``llrint``
12583 functions would, but without setting errno.
12585 Bit Manipulation Intrinsics
12586 ---------------------------
12588 LLVM provides intrinsics for a few important bit manipulation
12589 operations. These allow efficient code generation for some algorithms.
12591 '``llvm.bitreverse.*``' Intrinsics
12592 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12597 This is an overloaded intrinsic function. You can use bitreverse on any
12602 declare i16 @llvm.bitreverse.i16(i16 <id>)
12603 declare i32 @llvm.bitreverse.i32(i32 <id>)
12604 declare i64 @llvm.bitreverse.i64(i64 <id>)
12605 declare <4 x i32> @llvm.bitreverse.v4i32(<4 x i32> <id>)
12610 The '``llvm.bitreverse``' family of intrinsics is used to reverse the
12611 bitpattern of an integer value or vector of integer values; for example
12612 ``0b10110110`` becomes ``0b01101101``.
12617 The ``llvm.bitreverse.iN`` intrinsic returns an iN value that has bit
12618 ``M`` in the input moved to bit ``N-M`` in the output. The vector
12619 intrinsics, such as ``llvm.bitreverse.v4i32``, operate on a per-element
12620 basis and the element order is not affected.
12622 '``llvm.bswap.*``' Intrinsics
12623 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12628 This is an overloaded intrinsic function. You can use bswap on any
12629 integer type that is an even number of bytes (i.e. BitWidth % 16 == 0).
12633 declare i16 @llvm.bswap.i16(i16 <id>)
12634 declare i32 @llvm.bswap.i32(i32 <id>)
12635 declare i64 @llvm.bswap.i64(i64 <id>)
12636 declare <4 x i32> @llvm.bswap.v4i32(<4 x i32> <id>)
12641 The '``llvm.bswap``' family of intrinsics is used to byte swap an integer
12642 value or vector of integer values with an even number of bytes (positive
12643 multiple of 16 bits).
12648 The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high
12649 and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32``
12650 intrinsic returns an i32 value that has the four bytes of the input i32
12651 swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the
12652 returned i32 will have its bytes in 3, 2, 1, 0 order. The
12653 ``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this
12654 concept to additional even-byte lengths (6 bytes, 8 bytes and more,
12655 respectively). The vector intrinsics, such as ``llvm.bswap.v4i32``,
12656 operate on a per-element basis and the element order is not affected.
12658 '``llvm.ctpop.*``' Intrinsic
12659 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12664 This is an overloaded intrinsic. You can use llvm.ctpop on any integer
12665 bit width, or on any vector with integer elements. Not all targets
12666 support all bit widths or vector types, however.
12670 declare i8 @llvm.ctpop.i8(i8 <src>)
12671 declare i16 @llvm.ctpop.i16(i16 <src>)
12672 declare i32 @llvm.ctpop.i32(i32 <src>)
12673 declare i64 @llvm.ctpop.i64(i64 <src>)
12674 declare i256 @llvm.ctpop.i256(i256 <src>)
12675 declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)
12680 The '``llvm.ctpop``' family of intrinsics counts the number of bits set
12686 The only argument is the value to be counted. The argument may be of any
12687 integer type, or a vector with integer elements. The return type must
12688 match the argument type.
12693 The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within
12694 each element of a vector.
12696 '``llvm.ctlz.*``' Intrinsic
12697 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
12702 This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any
12703 integer bit width, or any vector whose elements are integers. Not all
12704 targets support all bit widths or vector types, however.
12708 declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>)
12709 declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>)
12710 declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>)
12711 declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>)
12712 declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
12713 declare <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
12718 The '``llvm.ctlz``' family of intrinsic functions counts the number of
12719 leading zeros in a variable.
12724 The first argument is the value to be counted. This argument may be of
12725 any integer type, or a vector with integer element type. The return
12726 type must match the first argument type.
12728 The second argument must be a constant and is a flag to indicate whether
12729 the intrinsic should ensure that a zero as the first argument produces a
12730 defined result. Historically some architectures did not provide a
12731 defined result for zero values as efficiently, and many algorithms are
12732 now predicated on avoiding zero-value inputs.
12737 The '``llvm.ctlz``' intrinsic counts the leading (most significant)
12738 zeros in a variable, or within each element of the vector. If
12739 ``src == 0`` then the result is the size in bits of the type of ``src``
12740 if ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
12741 ``llvm.ctlz(i32 2) = 30``.
12743 '``llvm.cttz.*``' Intrinsic
12744 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
12749 This is an overloaded intrinsic. You can use ``llvm.cttz`` on any
12750 integer bit width, or any vector of integer elements. Not all targets
12751 support all bit widths or vector types, however.
12755 declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>)
12756 declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>)
12757 declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>)
12758 declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>)
12759 declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
12760 declare <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
12765 The '``llvm.cttz``' family of intrinsic functions counts the number of
12771 The first argument is the value to be counted. This argument may be of
12772 any integer type, or a vector with integer element type. The return
12773 type must match the first argument type.
12775 The second argument must be a constant and is a flag to indicate whether
12776 the intrinsic should ensure that a zero as the first argument produces a
12777 defined result. Historically some architectures did not provide a
12778 defined result for zero values as efficiently, and many algorithms are
12779 now predicated on avoiding zero-value inputs.
12784 The '``llvm.cttz``' intrinsic counts the trailing (least significant)
12785 zeros in a variable, or within each element of a vector. If ``src == 0``
12786 then the result is the size in bits of the type of ``src`` if
12787 ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
12788 ``llvm.cttz(2) = 1``.
12792 '``llvm.fshl.*``' Intrinsic
12793 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
12798 This is an overloaded intrinsic. You can use ``llvm.fshl`` on any
12799 integer bit width or any vector of integer elements. Not all targets
12800 support all bit widths or vector types, however.
12804 declare i8 @llvm.fshl.i8 (i8 %a, i8 %b, i8 %c)
12805 declare i67 @llvm.fshl.i67(i67 %a, i67 %b, i67 %c)
12806 declare <2 x i32> @llvm.fshl.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c)
12811 The '``llvm.fshl``' family of intrinsic functions performs a funnel shift left:
12812 the first two values are concatenated as { %a : %b } (%a is the most significant
12813 bits of the wide value), the combined value is shifted left, and the most
12814 significant bits are extracted to produce a result that is the same size as the
12815 original arguments. If the first 2 arguments are identical, this is equivalent
12816 to a rotate left operation. For vector types, the operation occurs for each
12817 element of the vector. The shift argument is treated as an unsigned amount
12818 modulo the element size of the arguments.
12823 The first two arguments are the values to be concatenated. The third
12824 argument is the shift amount. The arguments may be any integer type or a
12825 vector with integer element type. All arguments and the return value must
12826 have the same type.
12831 .. code-block:: text
12833 %r = call i8 @llvm.fshl.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: msb_extract((concat(x, y) << (z % 8)), 8)
12834 %r = call i8 @llvm.fshl.i8(i8 255, i8 0, i8 15) ; %r = i8: 128 (0b10000000)
12835 %r = call i8 @llvm.fshl.i8(i8 15, i8 15, i8 11) ; %r = i8: 120 (0b01111000)
12836 %r = call i8 @llvm.fshl.i8(i8 0, i8 255, i8 8) ; %r = i8: 0 (0b00000000)
12838 '``llvm.fshr.*``' Intrinsic
12839 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
12844 This is an overloaded intrinsic. You can use ``llvm.fshr`` on any
12845 integer bit width or any vector of integer elements. Not all targets
12846 support all bit widths or vector types, however.
12850 declare i8 @llvm.fshr.i8 (i8 %a, i8 %b, i8 %c)
12851 declare i67 @llvm.fshr.i67(i67 %a, i67 %b, i67 %c)
12852 declare <2 x i32> @llvm.fshr.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c)
12857 The '``llvm.fshr``' family of intrinsic functions performs a funnel shift right:
12858 the first two values are concatenated as { %a : %b } (%a is the most significant
12859 bits of the wide value), the combined value is shifted right, and the least
12860 significant bits are extracted to produce a result that is the same size as the
12861 original arguments. If the first 2 arguments are identical, this is equivalent
12862 to a rotate right operation. For vector types, the operation occurs for each
12863 element of the vector. The shift argument is treated as an unsigned amount
12864 modulo the element size of the arguments.
12869 The first two arguments are the values to be concatenated. The third
12870 argument is the shift amount. The arguments may be any integer type or a
12871 vector with integer element type. All arguments and the return value must
12872 have the same type.
12877 .. code-block:: text
12879 %r = call i8 @llvm.fshr.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: lsb_extract((concat(x, y) >> (z % 8)), 8)
12880 %r = call i8 @llvm.fshr.i8(i8 255, i8 0, i8 15) ; %r = i8: 254 (0b11111110)
12881 %r = call i8 @llvm.fshr.i8(i8 15, i8 15, i8 11) ; %r = i8: 225 (0b11100001)
12882 %r = call i8 @llvm.fshr.i8(i8 0, i8 255, i8 8) ; %r = i8: 255 (0b11111111)
12884 Arithmetic with Overflow Intrinsics
12885 -----------------------------------
12887 LLVM provides intrinsics for fast arithmetic overflow checking.
12889 Each of these intrinsics returns a two-element struct. The first
12890 element of this struct contains the result of the corresponding
12891 arithmetic operation modulo 2\ :sup:`n`\ , where n is the bit width of
12892 the result. Therefore, for example, the first element of the struct
12893 returned by ``llvm.sadd.with.overflow.i32`` is always the same as the
12894 result of a 32-bit ``add`` instruction with the same operands, where
12895 the ``add`` is *not* modified by an ``nsw`` or ``nuw`` flag.
12897 The second element of the result is an ``i1`` that is 1 if the
12898 arithmetic operation overflowed and 0 otherwise. An operation
12899 overflows if, for any values of its operands ``A`` and ``B`` and for
12900 any ``N`` larger than the operands' width, ``ext(A op B) to iN`` is
12901 not equal to ``(ext(A) to iN) op (ext(B) to iN)`` where ``ext`` is
12902 ``sext`` for signed overflow and ``zext`` for unsigned overflow, and
12903 ``op`` is the underlying arithmetic operation.
12905 The behavior of these intrinsics is well-defined for all argument
12908 '``llvm.sadd.with.overflow.*``' Intrinsics
12909 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12914 This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``
12915 on any integer bit width or vectors of integers.
12919 declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
12920 declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
12921 declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
12922 declare {<4 x i32>, <4 x i1>} @llvm.sadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
12927 The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
12928 a signed addition of the two arguments, and indicate whether an overflow
12929 occurred during the signed summation.
12934 The arguments (%a and %b) and the first element of the result structure
12935 may be of integer types of any bit width, but they must have the same
12936 bit width. The second element of the result structure must be of type
12937 ``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
12943 The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
12944 a signed addition of the two variables. They return a structure --- the
12945 first element of which is the signed summation, and the second element
12946 of which is a bit specifying if the signed summation resulted in an
12952 .. code-block:: llvm
12954 %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
12955 %sum = extractvalue {i32, i1} %res, 0
12956 %obit = extractvalue {i32, i1} %res, 1
12957 br i1 %obit, label %overflow, label %normal
12959 '``llvm.uadd.with.overflow.*``' Intrinsics
12960 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12965 This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow``
12966 on any integer bit width or vectors of integers.
12970 declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
12971 declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
12972 declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
12973 declare {<4 x i32>, <4 x i1>} @llvm.uadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
12978 The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
12979 an unsigned addition of the two arguments, and indicate whether a carry
12980 occurred during the unsigned summation.
12985 The arguments (%a and %b) and the first element of the result structure
12986 may be of integer types of any bit width, but they must have the same
12987 bit width. The second element of the result structure must be of type
12988 ``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
12994 The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
12995 an unsigned addition of the two arguments. They return a structure --- the
12996 first element of which is the sum, and the second element of which is a
12997 bit specifying if the unsigned summation resulted in a carry.
13002 .. code-block:: llvm
13004 %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
13005 %sum = extractvalue {i32, i1} %res, 0
13006 %obit = extractvalue {i32, i1} %res, 1
13007 br i1 %obit, label %carry, label %normal
13009 '``llvm.ssub.with.overflow.*``' Intrinsics
13010 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13015 This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow``
13016 on any integer bit width or vectors of integers.
13020 declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
13021 declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
13022 declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
13023 declare {<4 x i32>, <4 x i1>} @llvm.ssub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
13028 The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
13029 a signed subtraction of the two arguments, and indicate whether an
13030 overflow occurred during the signed subtraction.
13035 The arguments (%a and %b) and the first element of the result structure
13036 may be of integer types of any bit width, but they must have the same
13037 bit width. The second element of the result structure must be of type
13038 ``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
13044 The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
13045 a signed subtraction of the two arguments. They return a structure --- the
13046 first element of which is the subtraction, and the second element of
13047 which is a bit specifying if the signed subtraction resulted in an
13053 .. code-block:: llvm
13055 %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
13056 %sum = extractvalue {i32, i1} %res, 0
13057 %obit = extractvalue {i32, i1} %res, 1
13058 br i1 %obit, label %overflow, label %normal
13060 '``llvm.usub.with.overflow.*``' Intrinsics
13061 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13066 This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow``
13067 on any integer bit width or vectors of integers.
13071 declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
13072 declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
13073 declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
13074 declare {<4 x i32>, <4 x i1>} @llvm.usub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
13079 The '``llvm.usub.with.overflow``' family of intrinsic functions perform
13080 an unsigned subtraction of the two arguments, and indicate whether an
13081 overflow occurred during the unsigned subtraction.
13086 The arguments (%a and %b) and the first element of the result structure
13087 may be of integer types of any bit width, but they must have the same
13088 bit width. The second element of the result structure must be of type
13089 ``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
13095 The '``llvm.usub.with.overflow``' family of intrinsic functions perform
13096 an unsigned subtraction of the two arguments. They return a structure ---
13097 the first element of which is the subtraction, and the second element of
13098 which is a bit specifying if the unsigned subtraction resulted in an
13104 .. code-block:: llvm
13106 %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
13107 %sum = extractvalue {i32, i1} %res, 0
13108 %obit = extractvalue {i32, i1} %res, 1
13109 br i1 %obit, label %overflow, label %normal
13111 '``llvm.smul.with.overflow.*``' Intrinsics
13112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13117 This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow``
13118 on any integer bit width or vectors of integers.
13122 declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
13123 declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
13124 declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
13125 declare {<4 x i32>, <4 x i1>} @llvm.smul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
13130 The '``llvm.smul.with.overflow``' family of intrinsic functions perform
13131 a signed multiplication of the two arguments, and indicate whether an
13132 overflow occurred during the signed multiplication.
13137 The arguments (%a and %b) and the first element of the result structure
13138 may be of integer types of any bit width, but they must have the same
13139 bit width. The second element of the result structure must be of type
13140 ``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
13146 The '``llvm.smul.with.overflow``' family of intrinsic functions perform
13147 a signed multiplication of the two arguments. They return a structure ---
13148 the first element of which is the multiplication, and the second element
13149 of which is a bit specifying if the signed multiplication resulted in an
13155 .. code-block:: llvm
13157 %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
13158 %sum = extractvalue {i32, i1} %res, 0
13159 %obit = extractvalue {i32, i1} %res, 1
13160 br i1 %obit, label %overflow, label %normal
13162 '``llvm.umul.with.overflow.*``' Intrinsics
13163 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13168 This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow``
13169 on any integer bit width or vectors of integers.
13173 declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
13174 declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
13175 declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
13176 declare {<4 x i32>, <4 x i1>} @llvm.umul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
13181 The '``llvm.umul.with.overflow``' family of intrinsic functions perform
13182 a unsigned multiplication of the two arguments, and indicate whether an
13183 overflow occurred during the unsigned multiplication.
13188 The arguments (%a and %b) and the first element of the result structure
13189 may be of integer types of any bit width, but they must have the same
13190 bit width. The second element of the result structure must be of type
13191 ``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
13197 The '``llvm.umul.with.overflow``' family of intrinsic functions perform
13198 an unsigned multiplication of the two arguments. They return a structure ---
13199 the first element of which is the multiplication, and the second
13200 element of which is a bit specifying if the unsigned multiplication
13201 resulted in an overflow.
13206 .. code-block:: llvm
13208 %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
13209 %sum = extractvalue {i32, i1} %res, 0
13210 %obit = extractvalue {i32, i1} %res, 1
13211 br i1 %obit, label %overflow, label %normal
13213 Saturation Arithmetic Intrinsics
13214 ---------------------------------
13216 Saturation arithmetic is a version of arithmetic in which operations are
13217 limited to a fixed range between a minimum and maximum value. If the result of
13218 an operation is greater than the maximum value, the result is set (or
13219 "clamped") to this maximum. If it is below the minimum, it is clamped to this
13223 '``llvm.sadd.sat.*``' Intrinsics
13224 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13229 This is an overloaded intrinsic. You can use ``llvm.sadd.sat``
13230 on any integer bit width or vectors of integers.
13234 declare i16 @llvm.sadd.sat.i16(i16 %a, i16 %b)
13235 declare i32 @llvm.sadd.sat.i32(i32 %a, i32 %b)
13236 declare i64 @llvm.sadd.sat.i64(i64 %a, i64 %b)
13237 declare <4 x i32> @llvm.sadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
13242 The '``llvm.sadd.sat``' family of intrinsic functions perform signed
13243 saturation addition on the 2 arguments.
13248 The arguments (%a and %b) and the result may be of integer types of any bit
13249 width, but they must have the same bit width. ``%a`` and ``%b`` are the two
13250 values that will undergo signed addition.
13255 The maximum value this operation can clamp to is the largest signed value
13256 representable by the bit width of the arguments. The minimum value is the
13257 smallest signed value representable by this bit width.
13263 .. code-block:: llvm
13265 %res = call i4 @llvm.sadd.sat.i4(i4 1, i4 2) ; %res = 3
13266 %res = call i4 @llvm.sadd.sat.i4(i4 5, i4 6) ; %res = 7
13267 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 2) ; %res = -2
13268 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 -5) ; %res = -8
13271 '``llvm.uadd.sat.*``' Intrinsics
13272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13277 This is an overloaded intrinsic. You can use ``llvm.uadd.sat``
13278 on any integer bit width or vectors of integers.
13282 declare i16 @llvm.uadd.sat.i16(i16 %a, i16 %b)
13283 declare i32 @llvm.uadd.sat.i32(i32 %a, i32 %b)
13284 declare i64 @llvm.uadd.sat.i64(i64 %a, i64 %b)
13285 declare <4 x i32> @llvm.uadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
13290 The '``llvm.uadd.sat``' family of intrinsic functions perform unsigned
13291 saturation addition on the 2 arguments.
13296 The arguments (%a and %b) and the result may be of integer types of any bit
13297 width, but they must have the same bit width. ``%a`` and ``%b`` are the two
13298 values that will undergo unsigned addition.
13303 The maximum value this operation can clamp to is the largest unsigned value
13304 representable by the bit width of the arguments. Because this is an unsigned
13305 operation, the result will never saturate towards zero.
13311 .. code-block:: llvm
13313 %res = call i4 @llvm.uadd.sat.i4(i4 1, i4 2) ; %res = 3
13314 %res = call i4 @llvm.uadd.sat.i4(i4 5, i4 6) ; %res = 11
13315 %res = call i4 @llvm.uadd.sat.i4(i4 8, i4 8) ; %res = 15
13318 '``llvm.ssub.sat.*``' Intrinsics
13319 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13324 This is an overloaded intrinsic. You can use ``llvm.ssub.sat``
13325 on any integer bit width or vectors of integers.
13329 declare i16 @llvm.ssub.sat.i16(i16 %a, i16 %b)
13330 declare i32 @llvm.ssub.sat.i32(i32 %a, i32 %b)
13331 declare i64 @llvm.ssub.sat.i64(i64 %a, i64 %b)
13332 declare <4 x i32> @llvm.ssub.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
13337 The '``llvm.ssub.sat``' family of intrinsic functions perform signed
13338 saturation subtraction on the 2 arguments.
13343 The arguments (%a and %b) and the result may be of integer types of any bit
13344 width, but they must have the same bit width. ``%a`` and ``%b`` are the two
13345 values that will undergo signed subtraction.
13350 The maximum value this operation can clamp to is the largest signed value
13351 representable by the bit width of the arguments. The minimum value is the
13352 smallest signed value representable by this bit width.
13358 .. code-block:: llvm
13360 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 1) ; %res = 1
13361 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 6) ; %res = -4
13362 %res = call i4 @llvm.ssub.sat.i4(i4 -4, i4 5) ; %res = -8
13363 %res = call i4 @llvm.ssub.sat.i4(i4 4, i4 -5) ; %res = 7
13366 '``llvm.usub.sat.*``' Intrinsics
13367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13372 This is an overloaded intrinsic. You can use ``llvm.usub.sat``
13373 on any integer bit width or vectors of integers.
13377 declare i16 @llvm.usub.sat.i16(i16 %a, i16 %b)
13378 declare i32 @llvm.usub.sat.i32(i32 %a, i32 %b)
13379 declare i64 @llvm.usub.sat.i64(i64 %a, i64 %b)
13380 declare <4 x i32> @llvm.usub.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
13385 The '``llvm.usub.sat``' family of intrinsic functions perform unsigned
13386 saturation subtraction on the 2 arguments.
13391 The arguments (%a and %b) and the result may be of integer types of any bit
13392 width, but they must have the same bit width. ``%a`` and ``%b`` are the two
13393 values that will undergo unsigned subtraction.
13398 The minimum value this operation can clamp to is 0, which is the smallest
13399 unsigned value representable by the bit width of the unsigned arguments.
13400 Because this is an unsigned operation, the result will never saturate towards
13401 the largest possible value representable by this bit width.
13407 .. code-block:: llvm
13409 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 1) ; %res = 1
13410 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 6) ; %res = 0
13413 Fixed Point Arithmetic Intrinsics
13414 ---------------------------------
13416 A fixed point number represents a real data type for a number that has a fixed
13417 number of digits after a radix point (equivalent to the decimal point '.').
13418 The number of digits after the radix point is referred as the ``scale``. These
13419 are useful for representing fractional values to a specific precision. The
13420 following intrinsics perform fixed point arithmetic operations on 2 operands
13421 of the same scale, specified as the third argument.
13423 The `llvm.*mul.fix` family of intrinsic functions represents a multiplication
13424 of fixed point numbers through scaled integers. Therefore, fixed point
13425 multplication can be represented as
13428 %result = call i4 @llvm.smul.fix.i4(i4 %a, i4 %b, i32 %scale)
13431 %a2 = sext i4 %a to i8
13432 %b2 = sext i4 %b to i8
13433 %mul = mul nsw nuw i8 %a, %b
13434 %scale2 = trunc i32 %scale to i8
13435 %r = ashr i8 %mul, i8 %scale2 ; this is for a target rounding down towards negative infinity
13436 %result = trunc i8 %r to i4
13438 For each of these functions, if the result cannot be represented exactly with
13439 the provided scale, the result is rounded. Rounding is unspecified since
13440 preferred rounding may vary for different targets. Rounding is specified
13441 through a target hook. Different pipelines should legalize or optimize this
13442 using the rounding specified by this hook if it is provided. Operations like
13443 constant folding, instruction combining, KnownBits, and ValueTracking should
13444 also use this hook, if provided, and not assume the direction of rounding. A
13445 rounded result must always be within one unit of precision from the true
13446 result. That is, the error between the returned result and the true result must
13447 be less than 1/2^(scale).
13450 '``llvm.smul.fix.*``' Intrinsics
13451 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13456 This is an overloaded intrinsic. You can use ``llvm.smul.fix``
13457 on any integer bit width or vectors of integers.
13461 declare i16 @llvm.smul.fix.i16(i16 %a, i16 %b, i32 %scale)
13462 declare i32 @llvm.smul.fix.i32(i32 %a, i32 %b, i32 %scale)
13463 declare i64 @llvm.smul.fix.i64(i64 %a, i64 %b, i32 %scale)
13464 declare <4 x i32> @llvm.smul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale)
13469 The '``llvm.smul.fix``' family of intrinsic functions perform signed
13470 fixed point multiplication on 2 arguments of the same scale.
13475 The arguments (%a and %b) and the result may be of integer types of any bit
13476 width, but they must have the same bit width. The arguments may also work with
13477 int vectors of the same length and int size. ``%a`` and ``%b`` are the two
13478 values that will undergo signed fixed point multiplication. The argument
13479 ``%scale`` represents the scale of both operands, and must be a constant
13485 This operation performs fixed point multiplication on the 2 arguments of a
13486 specified scale. The result will also be returned in the same scale specified
13487 in the third argument.
13489 If the result value cannot be precisely represented in the given scale, the
13490 value is rounded up or down to the closest representable value. The rounding
13491 direction is unspecified.
13493 It is undefined behavior if the result value does not fit within the range of
13494 the fixed point type.
13500 .. code-block:: llvm
13502 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6)
13503 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5)
13504 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 x -1 = -1.5)
13506 ; The result in the following could be rounded up to -2 or down to -2.5
13507 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -3, i32 1) ; %res = -5 (or -4) (1.5 x -1.5 = -2.25)
13510 '``llvm.umul.fix.*``' Intrinsics
13511 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13516 This is an overloaded intrinsic. You can use ``llvm.umul.fix``
13517 on any integer bit width or vectors of integers.
13521 declare i16 @llvm.umul.fix.i16(i16 %a, i16 %b, i32 %scale)
13522 declare i32 @llvm.umul.fix.i32(i32 %a, i32 %b, i32 %scale)
13523 declare i64 @llvm.umul.fix.i64(i64 %a, i64 %b, i32 %scale)
13524 declare <4 x i32> @llvm.umul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale)
13529 The '``llvm.umul.fix``' family of intrinsic functions perform unsigned
13530 fixed point multiplication on 2 arguments of the same scale.
13535 The arguments (%a and %b) and the result may be of integer types of any bit
13536 width, but they must have the same bit width. The arguments may also work with
13537 int vectors of the same length and int size. ``%a`` and ``%b`` are the two
13538 values that will undergo unsigned fixed point multiplication. The argument
13539 ``%scale`` represents the scale of both operands, and must be a constant
13545 This operation performs unsigned fixed point multiplication on the 2 arguments of a
13546 specified scale. The result will also be returned in the same scale specified
13547 in the third argument.
13549 If the result value cannot be precisely represented in the given scale, the
13550 value is rounded up or down to the closest representable value. The rounding
13551 direction is unspecified.
13553 It is undefined behavior if the result value does not fit within the range of
13554 the fixed point type.
13560 .. code-block:: llvm
13562 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6)
13563 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5)
13565 ; The result in the following could be rounded down to 3.5 or up to 4
13566 %res = call i4 @llvm.umul.fix.i4(i4 15, i4 1, i32 1) ; %res = 7 (or 8) (7.5 x 0.5 = 3.75)
13569 '``llvm.smul.fix.sat.*``' Intrinsics
13570 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13575 This is an overloaded intrinsic. You can use ``llvm.smul.fix.sat``
13576 on any integer bit width or vectors of integers.
13580 declare i16 @llvm.smul.fix.sat.i16(i16 %a, i16 %b, i32 %scale)
13581 declare i32 @llvm.smul.fix.sat.i32(i32 %a, i32 %b, i32 %scale)
13582 declare i64 @llvm.smul.fix.sat.i64(i64 %a, i64 %b, i32 %scale)
13583 declare <4 x i32> @llvm.smul.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale)
13588 The '``llvm.smul.fix.sat``' family of intrinsic functions perform signed
13589 fixed point saturation multiplication on 2 arguments of the same scale.
13594 The arguments (%a and %b) and the result may be of integer types of any bit
13595 width, but they must have the same bit width. ``%a`` and ``%b`` are the two
13596 values that will undergo signed fixed point multiplication. The argument
13597 ``%scale`` represents the scale of both operands, and must be a constant
13603 This operation performs fixed point multiplication on the 2 arguments of a
13604 specified scale. The result will also be returned in the same scale specified
13605 in the third argument.
13607 If the result value cannot be precisely represented in the given scale, the
13608 value is rounded up or down to the closest representable value. The rounding
13609 direction is unspecified.
13611 The maximum value this operation can clamp to is the largest signed value
13612 representable by the bit width of the first 2 arguments. The minimum value is the
13613 smallest signed value representable by this bit width.
13619 .. code-block:: llvm
13621 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6)
13622 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5)
13623 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 x -1 = -1.5)
13625 ; The result in the following could be rounded up to -2 or down to -2.5
13626 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 -3, i32 1) ; %res = -5 (or -4) (1.5 x -1.5 = -2.25)
13629 %res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 2, i32 0) ; %res = 7
13630 %res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 2, i32 2) ; %res = 7
13631 %res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 2, i32 2) ; %res = -8
13632 %res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 -2, i32 2) ; %res = 7
13634 ; Scale can affect the saturation result
13635 %res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 0) ; %res = 7 (2 x 4 -> clamped to 7)
13636 %res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 1) ; %res = 4 (1 x 2 = 2)
13639 Specialised Arithmetic Intrinsics
13640 ---------------------------------
13642 '``llvm.canonicalize.*``' Intrinsic
13643 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13650 declare float @llvm.canonicalize.f32(float %a)
13651 declare double @llvm.canonicalize.f64(double %b)
13656 The '``llvm.canonicalize.*``' intrinsic returns the platform specific canonical
13657 encoding of a floating-point number. This canonicalization is useful for
13658 implementing certain numeric primitives such as frexp. The canonical encoding is
13659 defined by IEEE-754-2008 to be:
13663 2.1.8 canonical encoding: The preferred encoding of a floating-point
13664 representation in a format. Applied to declets, significands of finite
13665 numbers, infinities, and NaNs, especially in decimal formats.
13667 This operation can also be considered equivalent to the IEEE-754-2008
13668 conversion of a floating-point value to the same format. NaNs are handled
13669 according to section 6.2.
13671 Examples of non-canonical encodings:
13673 - x87 pseudo denormals, pseudo NaNs, pseudo Infinity, Unnormals. These are
13674 converted to a canonical representation per hardware-specific protocol.
13675 - Many normal decimal floating-point numbers have non-canonical alternative
13677 - Some machines, like GPUs or ARMv7 NEON, do not support subnormal values.
13678 These are treated as non-canonical encodings of zero and will be flushed to
13679 a zero of the same sign by this operation.
13681 Note that per IEEE-754-2008 6.2, systems that support signaling NaNs with
13682 default exception handling must signal an invalid exception, and produce a
13685 This function should always be implementable as multiplication by 1.0, provided
13686 that the compiler does not constant fold the operation. Likewise, division by
13687 1.0 and ``llvm.minnum(x, x)`` are possible implementations. Addition with
13688 -0.0 is also sufficient provided that the rounding mode is not -Infinity.
13690 ``@llvm.canonicalize`` must preserve the equality relation. That is:
13692 - ``(@llvm.canonicalize(x) == x)`` is equivalent to ``(x == x)``
13693 - ``(@llvm.canonicalize(x) == @llvm.canonicalize(y))`` is equivalent to
13696 Additionally, the sign of zero must be conserved:
13697 ``@llvm.canonicalize(-0.0) = -0.0`` and ``@llvm.canonicalize(+0.0) = +0.0``
13699 The payload bits of a NaN must be conserved, with two exceptions.
13700 First, environments which use only a single canonical representation of NaN
13701 must perform said canonicalization. Second, SNaNs must be quieted per the
13704 The canonicalization operation may be optimized away if:
13706 - The input is known to be canonical. For example, it was produced by a
13707 floating-point operation that is required by the standard to be canonical.
13708 - The result is consumed only by (or fused with) other floating-point
13709 operations. That is, the bits of the floating-point value are not examined.
13711 '``llvm.fmuladd.*``' Intrinsic
13712 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13719 declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
13720 declare double @llvm.fmuladd.f64(double %a, double %b, double %c)
13725 The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add
13726 expressions that can be fused if the code generator determines that (a) the
13727 target instruction set has support for a fused operation, and (b) that the
13728 fused operation is more efficient than the equivalent, separate pair of mul
13729 and add instructions.
13734 The '``llvm.fmuladd.*``' intrinsics each take three arguments: two
13735 multiplicands, a and b, and an addend c.
13744 %0 = call float @llvm.fmuladd.f32(%a, %b, %c)
13746 is equivalent to the expression a \* b + c, except that rounding will
13747 not be performed between the multiplication and addition steps if the
13748 code generator fuses the operations. Fusion is not guaranteed, even if
13749 the target platform supports it. If a fused multiply-add is required the
13750 corresponding llvm.fma.\* intrinsic function should be used
13751 instead. This never sets errno, just as '``llvm.fma.*``'.
13756 .. code-block:: llvm
13758 %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c
13761 Experimental Vector Reduction Intrinsics
13762 ----------------------------------------
13764 Horizontal reductions of vectors can be expressed using the following
13765 intrinsics. Each one takes a vector operand as an input and applies its
13766 respective operation across all elements of the vector, returning a single
13767 scalar result of the same element type.
13770 '``llvm.experimental.vector.reduce.add.*``' Intrinsic
13771 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13778 declare i32 @llvm.experimental.vector.reduce.add.v4i32(<4 x i32> %a)
13779 declare i64 @llvm.experimental.vector.reduce.add.v2i64(<2 x i64> %a)
13784 The '``llvm.experimental.vector.reduce.add.*``' intrinsics do an integer ``ADD``
13785 reduction of a vector, returning the result as a scalar. The return type matches
13786 the element-type of the vector input.
13790 The argument to this intrinsic must be a vector of integer values.
13792 '``llvm.experimental.vector.reduce.v2.fadd.*``' Intrinsic
13793 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13800 declare float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float %start_value, <4 x float> %a)
13801 declare double @llvm.experimental.vector.reduce.v2.fadd.f64.v2f64(double %start_value, <2 x double> %a)
13806 The '``llvm.experimental.vector.reduce.v2.fadd.*``' intrinsics do a floating-point
13807 ``ADD`` reduction of a vector, returning the result as a scalar. The return type
13808 matches the element-type of the vector input.
13810 If the intrinsic call has the 'reassoc' or 'fast' flags set, then the
13811 reduction will not preserve the associativity of an equivalent scalarized
13812 counterpart. Otherwise the reduction will be *ordered*, thus implying that
13813 the operation respects the associativity of a scalarized reduction.
13818 The first argument to this intrinsic is a scalar start value for the reduction.
13819 The type of the start value matches the element-type of the vector input.
13820 The second argument must be a vector of floating-point values.
13827 %unord = call reassoc float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float 0.0, <4 x float> %input) ; unordered reduction
13828 %ord = call float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float %start_value, <4 x float> %input) ; ordered reduction
13831 '``llvm.experimental.vector.reduce.mul.*``' Intrinsic
13832 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13839 declare i32 @llvm.experimental.vector.reduce.mul.v4i32(<4 x i32> %a)
13840 declare i64 @llvm.experimental.vector.reduce.mul.v2i64(<2 x i64> %a)
13845 The '``llvm.experimental.vector.reduce.mul.*``' intrinsics do an integer ``MUL``
13846 reduction of a vector, returning the result as a scalar. The return type matches
13847 the element-type of the vector input.
13851 The argument to this intrinsic must be a vector of integer values.
13853 '``llvm.experimental.vector.reduce.v2.fmul.*``' Intrinsic
13854 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13861 declare float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float %start_value, <4 x float> %a)
13862 declare double @llvm.experimental.vector.reduce.v2.fmul.f64.v2f64(double %start_value, <2 x double> %a)
13867 The '``llvm.experimental.vector.reduce.v2.fmul.*``' intrinsics do a floating-point
13868 ``MUL`` reduction of a vector, returning the result as a scalar. The return type
13869 matches the element-type of the vector input.
13871 If the intrinsic call has the 'reassoc' or 'fast' flags set, then the
13872 reduction will not preserve the associativity of an equivalent scalarized
13873 counterpart. Otherwise the reduction will be *ordered*, thus implying that
13874 the operation respects the associativity of a scalarized reduction.
13879 The first argument to this intrinsic is a scalar start value for the reduction.
13880 The type of the start value matches the element-type of the vector input.
13881 The second argument must be a vector of floating-point values.
13888 %unord = call reassoc float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float 1.0, <4 x float> %input) ; unordered reduction
13889 %ord = call float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float %start_value, <4 x float> %input) ; ordered reduction
13891 '``llvm.experimental.vector.reduce.and.*``' Intrinsic
13892 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13899 declare i32 @llvm.experimental.vector.reduce.and.v4i32(<4 x i32> %a)
13904 The '``llvm.experimental.vector.reduce.and.*``' intrinsics do a bitwise ``AND``
13905 reduction of a vector, returning the result as a scalar. The return type matches
13906 the element-type of the vector input.
13910 The argument to this intrinsic must be a vector of integer values.
13912 '``llvm.experimental.vector.reduce.or.*``' Intrinsic
13913 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13920 declare i32 @llvm.experimental.vector.reduce.or.v4i32(<4 x i32> %a)
13925 The '``llvm.experimental.vector.reduce.or.*``' intrinsics do a bitwise ``OR`` reduction
13926 of a vector, returning the result as a scalar. The return type matches the
13927 element-type of the vector input.
13931 The argument to this intrinsic must be a vector of integer values.
13933 '``llvm.experimental.vector.reduce.xor.*``' Intrinsic
13934 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13941 declare i32 @llvm.experimental.vector.reduce.xor.v4i32(<4 x i32> %a)
13946 The '``llvm.experimental.vector.reduce.xor.*``' intrinsics do a bitwise ``XOR``
13947 reduction of a vector, returning the result as a scalar. The return type matches
13948 the element-type of the vector input.
13952 The argument to this intrinsic must be a vector of integer values.
13954 '``llvm.experimental.vector.reduce.smax.*``' Intrinsic
13955 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13962 declare i32 @llvm.experimental.vector.reduce.smax.v4i32(<4 x i32> %a)
13967 The '``llvm.experimental.vector.reduce.smax.*``' intrinsics do a signed integer
13968 ``MAX`` reduction of a vector, returning the result as a scalar. The return type
13969 matches the element-type of the vector input.
13973 The argument to this intrinsic must be a vector of integer values.
13975 '``llvm.experimental.vector.reduce.smin.*``' Intrinsic
13976 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13983 declare i32 @llvm.experimental.vector.reduce.smin.v4i32(<4 x i32> %a)
13988 The '``llvm.experimental.vector.reduce.smin.*``' intrinsics do a signed integer
13989 ``MIN`` reduction of a vector, returning the result as a scalar. The return type
13990 matches the element-type of the vector input.
13994 The argument to this intrinsic must be a vector of integer values.
13996 '``llvm.experimental.vector.reduce.umax.*``' Intrinsic
13997 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14004 declare i32 @llvm.experimental.vector.reduce.umax.v4i32(<4 x i32> %a)
14009 The '``llvm.experimental.vector.reduce.umax.*``' intrinsics do an unsigned
14010 integer ``MAX`` reduction of a vector, returning the result as a scalar. The
14011 return type matches the element-type of the vector input.
14015 The argument to this intrinsic must be a vector of integer values.
14017 '``llvm.experimental.vector.reduce.umin.*``' Intrinsic
14018 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14025 declare i32 @llvm.experimental.vector.reduce.umin.v4i32(<4 x i32> %a)
14030 The '``llvm.experimental.vector.reduce.umin.*``' intrinsics do an unsigned
14031 integer ``MIN`` reduction of a vector, returning the result as a scalar. The
14032 return type matches the element-type of the vector input.
14036 The argument to this intrinsic must be a vector of integer values.
14038 '``llvm.experimental.vector.reduce.fmax.*``' Intrinsic
14039 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14046 declare float @llvm.experimental.vector.reduce.fmax.v4f32(<4 x float> %a)
14047 declare double @llvm.experimental.vector.reduce.fmax.v2f64(<2 x double> %a)
14052 The '``llvm.experimental.vector.reduce.fmax.*``' intrinsics do a floating-point
14053 ``MAX`` reduction of a vector, returning the result as a scalar. The return type
14054 matches the element-type of the vector input.
14056 If the intrinsic call has the ``nnan`` fast-math flag then the operation can
14057 assume that NaNs are not present in the input vector.
14061 The argument to this intrinsic must be a vector of floating-point values.
14063 '``llvm.experimental.vector.reduce.fmin.*``' Intrinsic
14064 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14071 declare float @llvm.experimental.vector.reduce.fmin.v4f32(<4 x float> %a)
14072 declare double @llvm.experimental.vector.reduce.fmin.v2f64(<2 x double> %a)
14077 The '``llvm.experimental.vector.reduce.fmin.*``' intrinsics do a floating-point
14078 ``MIN`` reduction of a vector, returning the result as a scalar. The return type
14079 matches the element-type of the vector input.
14081 If the intrinsic call has the ``nnan`` fast-math flag then the operation can
14082 assume that NaNs are not present in the input vector.
14086 The argument to this intrinsic must be a vector of floating-point values.
14088 Half Precision Floating-Point Intrinsics
14089 ----------------------------------------
14091 For most target platforms, half precision floating-point is a
14092 storage-only format. This means that it is a dense encoding (in memory)
14093 but does not support computation in the format.
14095 This means that code must first load the half-precision floating-point
14096 value as an i16, then convert it to float with
14097 :ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can
14098 then be performed on the float value (including extending to double
14099 etc). To store the value back to memory, it is first converted to float
14100 if needed, then converted to i16 with
14101 :ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an
14104 .. _int_convert_to_fp16:
14106 '``llvm.convert.to.fp16``' Intrinsic
14107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14114 declare i16 @llvm.convert.to.fp16.f32(float %a)
14115 declare i16 @llvm.convert.to.fp16.f64(double %a)
14120 The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
14121 conventional floating-point type to half precision floating-point format.
14126 The intrinsic function contains single argument - the value to be
14132 The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
14133 conventional floating-point format to half precision floating-point format. The
14134 return value is an ``i16`` which contains the converted number.
14139 .. code-block:: llvm
14141 %res = call i16 @llvm.convert.to.fp16.f32(float %a)
14142 store i16 %res, i16* @x, align 2
14144 .. _int_convert_from_fp16:
14146 '``llvm.convert.from.fp16``' Intrinsic
14147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14154 declare float @llvm.convert.from.fp16.f32(i16 %a)
14155 declare double @llvm.convert.from.fp16.f64(i16 %a)
14160 The '``llvm.convert.from.fp16``' intrinsic function performs a
14161 conversion from half precision floating-point format to single precision
14162 floating-point format.
14167 The intrinsic function contains single argument - the value to be
14173 The '``llvm.convert.from.fp16``' intrinsic function performs a
14174 conversion from half single precision floating-point format to single
14175 precision floating-point format. The input half-float value is
14176 represented by an ``i16`` value.
14181 .. code-block:: llvm
14183 %a = load i16, i16* @x, align 2
14184 %res = call float @llvm.convert.from.fp16(i16 %a)
14186 .. _dbg_intrinsics:
14188 Debugger Intrinsics
14189 -------------------
14191 The LLVM debugger intrinsics (which all start with ``llvm.dbg.``
14192 prefix), are described in the `LLVM Source Level
14193 Debugging <SourceLevelDebugging.html#format-common-intrinsics>`_
14196 Exception Handling Intrinsics
14197 -----------------------------
14199 The LLVM exception handling intrinsics (which all start with
14200 ``llvm.eh.`` prefix), are described in the `LLVM Exception
14201 Handling <ExceptionHandling.html#format-common-intrinsics>`_ document.
14203 .. _int_trampoline:
14205 Trampoline Intrinsics
14206 ---------------------
14208 These intrinsics make it possible to excise one parameter, marked with
14209 the :ref:`nest <nest>` attribute, from a function. The result is a
14210 callable function pointer lacking the nest parameter - the caller does
14211 not need to provide a value for it. Instead, the value to use is stored
14212 in advance in a "trampoline", a block of memory usually allocated on the
14213 stack, which also contains code to splice the nest value into the
14214 argument list. This is used to implement the GCC nested function address
14217 For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)``
14218 then the resulting function pointer has signature ``i32 (i32, i32)*``.
14219 It can be created as follows:
14221 .. code-block:: llvm
14223 %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
14224 %tramp1 = getelementptr [10 x i8], [10 x i8]* %tramp, i32 0, i32 0
14225 call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
14226 %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
14227 %fp = bitcast i8* %p to i32 (i32, i32)*
14229 The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to
14230 ``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``.
14234 '``llvm.init.trampoline``' Intrinsic
14235 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14242 declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
14247 This fills the memory pointed to by ``tramp`` with executable code,
14248 turning it into a trampoline.
14253 The ``llvm.init.trampoline`` intrinsic takes three arguments, all
14254 pointers. The ``tramp`` argument must point to a sufficiently large and
14255 sufficiently aligned block of memory; this memory is written to by the
14256 intrinsic. Note that the size and the alignment are target-specific -
14257 LLVM currently provides no portable way of determining them, so a
14258 front-end that generates this intrinsic needs to have some
14259 target-specific knowledge. The ``func`` argument must hold a function
14260 bitcast to an ``i8*``.
14265 The block of memory pointed to by ``tramp`` is filled with target
14266 dependent code, turning it into a function. Then ``tramp`` needs to be
14267 passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can
14268 be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new
14269 function's signature is the same as that of ``func`` with any arguments
14270 marked with the ``nest`` attribute removed. At most one such ``nest``
14271 argument is allowed, and it must be of pointer type. Calling the new
14272 function is equivalent to calling ``func`` with the same argument list,
14273 but with ``nval`` used for the missing ``nest`` argument. If, after
14274 calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is
14275 modified, then the effect of any later call to the returned function
14276 pointer is undefined.
14280 '``llvm.adjust.trampoline``' Intrinsic
14281 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14288 declare i8* @llvm.adjust.trampoline(i8* <tramp>)
14293 This performs any required machine-specific adjustment to the address of
14294 a trampoline (passed as ``tramp``).
14299 ``tramp`` must point to a block of memory which already has trampoline
14300 code filled in by a previous call to
14301 :ref:`llvm.init.trampoline <int_it>`.
14306 On some architectures the address of the code to be executed needs to be
14307 different than the address where the trampoline is actually stored. This
14308 intrinsic returns the executable address corresponding to ``tramp``
14309 after performing the required machine specific adjustments. The pointer
14310 returned can then be :ref:`bitcast and executed <int_trampoline>`.
14312 .. _int_mload_mstore:
14314 Masked Vector Load and Store Intrinsics
14315 ---------------------------------------
14317 LLVM provides intrinsics for predicated vector load and store operations. The predicate is specified by a mask operand, which holds one bit per vector element, switching the associated vector lane on or off. The memory addresses corresponding to the "off" lanes are not accessed. When all bits of the mask are on, the intrinsic is identical to a regular vector load or store. When all bits are off, no memory is accessed.
14321 '``llvm.masked.load.*``' Intrinsics
14322 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14326 This is an overloaded intrinsic. The loaded data is a vector of any integer, floating-point or pointer data type.
14330 declare <16 x float> @llvm.masked.load.v16f32.p0v16f32 (<16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>)
14331 declare <2 x double> @llvm.masked.load.v2f64.p0v2f64 (<2 x double>* <ptr>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>)
14332 ;; The data is a vector of pointers to double
14333 declare <8 x double*> @llvm.masked.load.v8p0f64.p0v8p0f64 (<8 x double*>* <ptr>, i32 <alignment>, <8 x i1> <mask>, <8 x double*> <passthru>)
14334 ;; The data is a vector of function pointers
14335 declare <8 x i32 ()*> @llvm.masked.load.v8p0f_i32f.p0v8p0f_i32f (<8 x i32 ()*>* <ptr>, i32 <alignment>, <8 x i1> <mask>, <8 x i32 ()*> <passthru>)
14340 Reads a vector from memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. The masked-off lanes in the result vector are taken from the corresponding lanes of the '``passthru``' operand.
14346 The first operand is the base pointer for the load. The second operand is the alignment of the source location. It must be a constant integer value. The third operand, mask, is a vector of boolean values with the same number of elements as the return type. The fourth is a pass-through value that is used to fill the masked-off lanes of the result. The return type, underlying type of the base pointer and the type of the '``passthru``' operand are the same vector types.
14352 The '``llvm.masked.load``' intrinsic is designed for conditional reading of selected vector elements in a single IR operation. It is useful for targets that support vector masked loads and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar load operations.
14353 The result of this operation is equivalent to a regular vector load instruction followed by a 'select' between the loaded and the passthru values, predicated on the same mask. However, using this intrinsic prevents exceptions on memory access to masked-off lanes.
14358 %res = call <16 x float> @llvm.masked.load.v16f32.p0v16f32 (<16 x float>* %ptr, i32 4, <16 x i1>%mask, <16 x float> %passthru)
14360 ;; The result of the two following instructions is identical aside from potential memory access exception
14361 %loadlal = load <16 x float>, <16 x float>* %ptr, align 4
14362 %res = select <16 x i1> %mask, <16 x float> %loadlal, <16 x float> %passthru
14366 '``llvm.masked.store.*``' Intrinsics
14367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14371 This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type.
14375 declare void @llvm.masked.store.v8i32.p0v8i32 (<8 x i32> <value>, <8 x i32>* <ptr>, i32 <alignment>, <8 x i1> <mask>)
14376 declare void @llvm.masked.store.v16f32.p0v16f32 (<16 x float> <value>, <16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>)
14377 ;; The data is a vector of pointers to double
14378 declare void @llvm.masked.store.v8p0f64.p0v8p0f64 (<8 x double*> <value>, <8 x double*>* <ptr>, i32 <alignment>, <8 x i1> <mask>)
14379 ;; The data is a vector of function pointers
14380 declare void @llvm.masked.store.v4p0f_i32f.p0v4p0f_i32f (<4 x i32 ()*> <value>, <4 x i32 ()*>* <ptr>, i32 <alignment>, <4 x i1> <mask>)
14385 Writes a vector to memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes.
14390 The first operand is the vector value to be written to memory. The second operand is the base pointer for the store, it has the same underlying type as the value operand. The third operand is the alignment of the destination location. The fourth operand, mask, is a vector of boolean values. The types of the mask and the value operand must have the same number of vector elements.
14396 The '``llvm.masked.store``' intrinsics is designed for conditional writing of selected vector elements in a single IR operation. It is useful for targets that support vector masked store and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
14397 The result of this operation is equivalent to a load-modify-store sequence. However, using this intrinsic prevents exceptions and data races on memory access to masked-off lanes.
14401 call void @llvm.masked.store.v16f32.p0v16f32(<16 x float> %value, <16 x float>* %ptr, i32 4, <16 x i1> %mask)
14403 ;; The result of the following instructions is identical aside from potential data races and memory access exceptions
14404 %oldval = load <16 x float>, <16 x float>* %ptr, align 4
14405 %res = select <16 x i1> %mask, <16 x float> %value, <16 x float> %oldval
14406 store <16 x float> %res, <16 x float>* %ptr, align 4
14409 Masked Vector Gather and Scatter Intrinsics
14410 -------------------------------------------
14412 LLVM provides intrinsics for vector gather and scatter operations. They are similar to :ref:`Masked Vector Load and Store <int_mload_mstore>`, except they are designed for arbitrary memory accesses, rather than sequential memory accesses. Gather and scatter also employ a mask operand, which holds one bit per vector element, switching the associated vector lane on or off. The memory addresses corresponding to the "off" lanes are not accessed. When all bits are off, no memory is accessed.
14416 '``llvm.masked.gather.*``' Intrinsics
14417 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14421 This is an overloaded intrinsic. The loaded data are multiple scalar values of any integer, floating-point or pointer data type gathered together into one vector.
14425 declare <16 x float> @llvm.masked.gather.v16f32.v16p0f32 (<16 x float*> <ptrs>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>)
14426 declare <2 x double> @llvm.masked.gather.v2f64.v2p1f64 (<2 x double addrspace(1)*> <ptrs>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>)
14427 declare <8 x float*> @llvm.masked.gather.v8p0f32.v8p0p0f32 (<8 x float**> <ptrs>, i32 <alignment>, <8 x i1> <mask>, <8 x float*> <passthru>)
14432 Reads scalar values from arbitrary memory locations and gathers them into one vector. The memory locations are provided in the vector of pointers '``ptrs``'. The memory is accessed according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. The masked-off lanes in the result vector are taken from the corresponding lanes of the '``passthru``' operand.
14438 The first operand is a vector of pointers which holds all memory addresses to read. The second operand is an alignment of the source addresses. It must be a constant integer value. The third operand, mask, is a vector of boolean values with the same number of elements as the return type. The fourth is a pass-through value that is used to fill the masked-off lanes of the result. The return type, underlying type of the vector of pointers and the type of the '``passthru``' operand are the same vector types.
14444 The '``llvm.masked.gather``' intrinsic is designed for conditional reading of multiple scalar values from arbitrary memory locations in a single IR operation. It is useful for targets that support vector masked gathers and allows vectorizing basic blocks with data and control divergence. Other targets may support this intrinsic differently, for example by lowering it into a sequence of scalar load operations.
14445 The semantics of this operation are equivalent to a sequence of conditional scalar loads with subsequent gathering all loaded values into a single vector. The mask restricts memory access to certain lanes and facilitates vectorization of predicated basic blocks.
14450 %res = call <4 x double> @llvm.masked.gather.v4f64.v4p0f64 (<4 x double*> %ptrs, i32 8, <4 x i1> <i1 true, i1 true, i1 true, i1 true>, <4 x double> undef)
14452 ;; The gather with all-true mask is equivalent to the following instruction sequence
14453 %ptr0 = extractelement <4 x double*> %ptrs, i32 0
14454 %ptr1 = extractelement <4 x double*> %ptrs, i32 1
14455 %ptr2 = extractelement <4 x double*> %ptrs, i32 2
14456 %ptr3 = extractelement <4 x double*> %ptrs, i32 3
14458 %val0 = load double, double* %ptr0, align 8
14459 %val1 = load double, double* %ptr1, align 8
14460 %val2 = load double, double* %ptr2, align 8
14461 %val3 = load double, double* %ptr3, align 8
14463 %vec0 = insertelement <4 x double>undef, %val0, 0
14464 %vec01 = insertelement <4 x double>%vec0, %val1, 1
14465 %vec012 = insertelement <4 x double>%vec01, %val2, 2
14466 %vec0123 = insertelement <4 x double>%vec012, %val3, 3
14470 '``llvm.masked.scatter.*``' Intrinsics
14471 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14475 This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type. Each vector element is stored in an arbitrary memory address. Scatter with overlapping addresses is guaranteed to be ordered from least-significant to most-significant element.
14479 declare void @llvm.masked.scatter.v8i32.v8p0i32 (<8 x i32> <value>, <8 x i32*> <ptrs>, i32 <alignment>, <8 x i1> <mask>)
14480 declare void @llvm.masked.scatter.v16f32.v16p1f32 (<16 x float> <value>, <16 x float addrspace(1)*> <ptrs>, i32 <alignment>, <16 x i1> <mask>)
14481 declare void @llvm.masked.scatter.v4p0f64.v4p0p0f64 (<4 x double*> <value>, <4 x double**> <ptrs>, i32 <alignment>, <4 x i1> <mask>)
14486 Writes each element from the value vector to the corresponding memory address. The memory addresses are represented as a vector of pointers. Writing is done according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes.
14491 The first operand is a vector value to be written to memory. The second operand is a vector of pointers, pointing to where the value elements should be stored. It has the same underlying type as the value operand. The third operand is an alignment of the destination addresses. The fourth operand, mask, is a vector of boolean values. The types of the mask and the value operand must have the same number of vector elements.
14497 The '``llvm.masked.scatter``' intrinsics is designed for writing selected vector elements to arbitrary memory addresses in a single IR operation. The operation may be conditional, when not all bits in the mask are switched on. It is useful for targets that support vector masked scatter and allows vectorizing basic blocks with data and control divergence. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
14501 ;; This instruction unconditionally stores data vector in multiple addresses
14502 call @llvm.masked.scatter.v8i32.v8p0i32 (<8 x i32> %value, <8 x i32*> %ptrs, i32 4, <8 x i1> <true, true, .. true>)
14504 ;; It is equivalent to a list of scalar stores
14505 %val0 = extractelement <8 x i32> %value, i32 0
14506 %val1 = extractelement <8 x i32> %value, i32 1
14508 %val7 = extractelement <8 x i32> %value, i32 7
14509 %ptr0 = extractelement <8 x i32*> %ptrs, i32 0
14510 %ptr1 = extractelement <8 x i32*> %ptrs, i32 1
14512 %ptr7 = extractelement <8 x i32*> %ptrs, i32 7
14513 ;; Note: the order of the following stores is important when they overlap:
14514 store i32 %val0, i32* %ptr0, align 4
14515 store i32 %val1, i32* %ptr1, align 4
14517 store i32 %val7, i32* %ptr7, align 4
14520 Masked Vector Expanding Load and Compressing Store Intrinsics
14521 -------------------------------------------------------------
14523 LLVM provides intrinsics for expanding load and compressing store operations. Data selected from a vector according to a mask is stored in consecutive memory addresses (compressed store), and vice-versa (expanding load). These operations effective map to "if (cond.i) a[j++] = v.i" and "if (cond.i) v.i = a[j++]" patterns, respectively. Note that when the mask starts with '1' bits followed by '0' bits, these operations are identical to :ref:`llvm.masked.store <int_mstore>` and :ref:`llvm.masked.load <int_mload>`.
14525 .. _int_expandload:
14527 '``llvm.masked.expandload.*``' Intrinsics
14528 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14532 This is an overloaded intrinsic. Several values of integer, floating point or pointer data type are loaded from consecutive memory addresses and stored into the elements of a vector according to the mask.
14536 declare <16 x float> @llvm.masked.expandload.v16f32 (float* <ptr>, <16 x i1> <mask>, <16 x float> <passthru>)
14537 declare <2 x i64> @llvm.masked.expandload.v2i64 (i64* <ptr>, <2 x i1> <mask>, <2 x i64> <passthru>)
14542 Reads a number of scalar values sequentially from memory location provided in '``ptr``' and spreads them in a vector. The '``mask``' holds a bit for each vector lane. The number of elements read from memory is equal to the number of '1' bits in the mask. The loaded elements are positioned in the destination vector according to the sequence of '1' and '0' bits in the mask. E.g., if the mask vector is '10010001', "explandload" reads 3 values from memory addresses ptr, ptr+1, ptr+2 and places them in lanes 0, 3 and 7 accordingly. The masked-off lanes are filled by elements from the corresponding lanes of the '``passthru``' operand.
14548 The first operand is the base pointer for the load. It has the same underlying type as the element of the returned vector. The second operand, mask, is a vector of boolean values with the same number of elements as the return type. The third is a pass-through value that is used to fill the masked-off lanes of the result. The return type and the type of the '``passthru``' operand have the same vector type.
14553 The '``llvm.masked.expandload``' intrinsic is designed for reading multiple scalar values from adjacent memory addresses into possibly non-adjacent vector lanes. It is useful for targets that support vector expanding loads and allows vectorizing loop with cross-iteration dependency like in the following example:
14557 // In this loop we load from B and spread the elements into array A.
14558 double *A, B; int *C;
14559 for (int i = 0; i < size; ++i) {
14565 .. code-block:: llvm
14567 ; Load several elements from array B and expand them in a vector.
14568 ; The number of loaded elements is equal to the number of '1' elements in the Mask.
14569 %Tmp = call <8 x double> @llvm.masked.expandload.v8f64(double* %Bptr, <8 x i1> %Mask, <8 x double> undef)
14570 ; Store the result in A
14571 call void @llvm.masked.store.v8f64.p0v8f64(<8 x double> %Tmp, <8 x double>* %Aptr, i32 8, <8 x i1> %Mask)
14573 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask.
14574 %MaskI = bitcast <8 x i1> %Mask to i8
14575 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI)
14576 %MaskI64 = zext i8 %MaskIPopcnt to i64
14577 %BNextInd = add i64 %BInd, %MaskI64
14580 Other targets may support this intrinsic differently, for example, by lowering it into a sequence of conditional scalar load operations and shuffles.
14581 If all mask elements are '1', the intrinsic behavior is equivalent to the regular unmasked vector load.
14583 .. _int_compressstore:
14585 '``llvm.masked.compressstore.*``' Intrinsics
14586 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14590 This is an overloaded intrinsic. A number of scalar values of integer, floating point or pointer data type are collected from an input vector and stored into adjacent memory addresses. A mask defines which elements to collect from the vector.
14594 declare void @llvm.masked.compressstore.v8i32 (<8 x i32> <value>, i32* <ptr>, <8 x i1> <mask>)
14595 declare void @llvm.masked.compressstore.v16f32 (<16 x float> <value>, float* <ptr>, <16 x i1> <mask>)
14600 Selects elements from input vector '``value``' according to the '``mask``'. All selected elements are written into adjacent memory addresses starting at address '`ptr`', from lower to higher. The mask holds a bit for each vector lane, and is used to select elements to be stored. The number of elements to be stored is equal to the number of active bits in the mask.
14605 The first operand is the input vector, from which elements are collected and written to memory. The second operand is the base pointer for the store, it has the same underlying type as the element of the input vector operand. The third operand is the mask, a vector of boolean values. The mask and the input vector must have the same number of vector elements.
14611 The '``llvm.masked.compressstore``' intrinsic is designed for compressing data in memory. It allows to collect elements from possibly non-adjacent lanes of a vector and store them contiguously in memory in one IR operation. It is useful for targets that support compressing store operations and allows vectorizing loops with cross-iteration dependences like in the following example:
14615 // In this loop we load elements from A and store them consecutively in B
14616 double *A, B; int *C;
14617 for (int i = 0; i < size; ++i) {
14623 .. code-block:: llvm
14625 ; Load elements from A.
14626 %Tmp = call <8 x double> @llvm.masked.load.v8f64.p0v8f64(<8 x double>* %Aptr, i32 8, <8 x i1> %Mask, <8 x double> undef)
14627 ; Store all selected elements consecutively in array B
14628 call <void> @llvm.masked.compressstore.v8f64(<8 x double> %Tmp, double* %Bptr, <8 x i1> %Mask)
14630 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask.
14631 %MaskI = bitcast <8 x i1> %Mask to i8
14632 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI)
14633 %MaskI64 = zext i8 %MaskIPopcnt to i64
14634 %BNextInd = add i64 %BInd, %MaskI64
14637 Other targets may support this intrinsic differently, for example, by lowering it into a sequence of branches that guard scalar store operations.
14643 This class of intrinsics provides information about the lifetime of
14644 memory objects and ranges where variables are immutable.
14648 '``llvm.lifetime.start``' Intrinsic
14649 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14656 declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
14661 The '``llvm.lifetime.start``' intrinsic specifies the start of a memory
14667 The first argument is a constant integer representing the size of the
14668 object, or -1 if it is variable sized. The second argument is a pointer
14674 This intrinsic indicates that before this point in the code, the value
14675 of the memory pointed to by ``ptr`` is dead. This means that it is known
14676 to never be used and has an undefined value. A load from the pointer
14677 that precedes this intrinsic can be replaced with ``'undef'``.
14681 '``llvm.lifetime.end``' Intrinsic
14682 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14689 declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
14694 The '``llvm.lifetime.end``' intrinsic specifies the end of a memory
14700 The first argument is a constant integer representing the size of the
14701 object, or -1 if it is variable sized. The second argument is a pointer
14707 This intrinsic indicates that after this point in the code, the value of
14708 the memory pointed to by ``ptr`` is dead. This means that it is known to
14709 never be used and has an undefined value. Any stores into the memory
14710 object following this intrinsic may be removed as dead.
14712 '``llvm.invariant.start``' Intrinsic
14713 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14717 This is an overloaded intrinsic. The memory object can belong to any address space.
14721 declare {}* @llvm.invariant.start.p0i8(i64 <size>, i8* nocapture <ptr>)
14726 The '``llvm.invariant.start``' intrinsic specifies that the contents of
14727 a memory object will not change.
14732 The first argument is a constant integer representing the size of the
14733 object, or -1 if it is variable sized. The second argument is a pointer
14739 This intrinsic indicates that until an ``llvm.invariant.end`` that uses
14740 the return value, the referenced memory location is constant and
14743 '``llvm.invariant.end``' Intrinsic
14744 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14748 This is an overloaded intrinsic. The memory object can belong to any address space.
14752 declare void @llvm.invariant.end.p0i8({}* <start>, i64 <size>, i8* nocapture <ptr>)
14757 The '``llvm.invariant.end``' intrinsic specifies that the contents of a
14758 memory object are mutable.
14763 The first argument is the matching ``llvm.invariant.start`` intrinsic.
14764 The second argument is a constant integer representing the size of the
14765 object, or -1 if it is variable sized and the third argument is a
14766 pointer to the object.
14771 This intrinsic indicates that the memory is mutable again.
14773 '``llvm.launder.invariant.group``' Intrinsic
14774 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14778 This is an overloaded intrinsic. The memory object can belong to any address
14779 space. The returned pointer must belong to the same address space as the
14784 declare i8* @llvm.launder.invariant.group.p0i8(i8* <ptr>)
14789 The '``llvm.launder.invariant.group``' intrinsic can be used when an invariant
14790 established by ``invariant.group`` metadata no longer holds, to obtain a new
14791 pointer value that carries fresh invariant group information. It is an
14792 experimental intrinsic, which means that its semantics might change in the
14799 The ``llvm.launder.invariant.group`` takes only one argument, which is a pointer
14805 Returns another pointer that aliases its argument but which is considered different
14806 for the purposes of ``load``/``store`` ``invariant.group`` metadata.
14807 It does not read any accessible memory and the execution can be speculated.
14809 '``llvm.strip.invariant.group``' Intrinsic
14810 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14814 This is an overloaded intrinsic. The memory object can belong to any address
14815 space. The returned pointer must belong to the same address space as the
14820 declare i8* @llvm.strip.invariant.group.p0i8(i8* <ptr>)
14825 The '``llvm.strip.invariant.group``' intrinsic can be used when an invariant
14826 established by ``invariant.group`` metadata no longer holds, to obtain a new pointer
14827 value that does not carry the invariant information. It is an experimental
14828 intrinsic, which means that its semantics might change in the future.
14834 The ``llvm.strip.invariant.group`` takes only one argument, which is a pointer
14840 Returns another pointer that aliases its argument but which has no associated
14841 ``invariant.group`` metadata.
14842 It does not read any memory and can be speculated.
14848 Constrained Floating-Point Intrinsics
14849 -------------------------------------
14851 These intrinsics are used to provide special handling of floating-point
14852 operations when specific rounding mode or floating-point exception behavior is
14853 required. By default, LLVM optimization passes assume that the rounding mode is
14854 round-to-nearest and that floating-point exceptions will not be monitored.
14855 Constrained FP intrinsics are used to support non-default rounding modes and
14856 accurately preserve exception behavior without compromising LLVM's ability to
14857 optimize FP code when the default behavior is used.
14859 Each of these intrinsics corresponds to a normal floating-point operation. The
14860 first two arguments and the return value are the same as the corresponding FP
14863 The third argument is a metadata argument specifying the rounding mode to be
14864 assumed. This argument must be one of the following strings:
14874 If this argument is "round.dynamic" optimization passes must assume that the
14875 rounding mode is unknown and may change at runtime. No transformations that
14876 depend on rounding mode may be performed in this case.
14878 The other possible values for the rounding mode argument correspond to the
14879 similarly named IEEE rounding modes. If the argument is any of these values
14880 optimization passes may perform transformations as long as they are consistent
14881 with the specified rounding mode.
14883 For example, 'x-0'->'x' is not a valid transformation if the rounding mode is
14884 "round.downward" or "round.dynamic" because if the value of 'x' is +0 then
14885 'x-0' should evaluate to '-0' when rounding downward. However, this
14886 transformation is legal for all other rounding modes.
14888 For values other than "round.dynamic" optimization passes may assume that the
14889 actual runtime rounding mode (as defined in a target-specific manner) matches
14890 the specified rounding mode, but this is not guaranteed. Using a specific
14891 non-dynamic rounding mode which does not match the actual rounding mode at
14892 runtime results in undefined behavior.
14894 The fourth argument to the constrained floating-point intrinsics specifies the
14895 required exception behavior. This argument must be one of the following
14904 If this argument is "fpexcept.ignore" optimization passes may assume that the
14905 exception status flags will not be read and that floating-point exceptions will
14906 be masked. This allows transformations to be performed that may change the
14907 exception semantics of the original code. For example, FP operations may be
14908 speculatively executed in this case whereas they must not be for either of the
14909 other possible values of this argument.
14911 If the exception behavior argument is "fpexcept.maytrap" optimization passes
14912 must avoid transformations that may raise exceptions that would not have been
14913 raised by the original code (such as speculatively executing FP operations), but
14914 passes are not required to preserve all exceptions that are implied by the
14915 original code. For example, exceptions may be potentially hidden by constant
14918 If the exception behavior argument is "fpexcept.strict" all transformations must
14919 strictly preserve the floating-point exception semantics of the original code.
14920 Any FP exception that would have been raised by the original code must be raised
14921 by the transformed code, and the transformed code must not raise any FP
14922 exceptions that would not have been raised by the original code. This is the
14923 exception behavior argument that will be used if the code being compiled reads
14924 the FP exception status flags, but this mode can also be used with code that
14925 unmasks FP exceptions.
14927 The number and order of floating-point exceptions is NOT guaranteed. For
14928 example, a series of FP operations that each may raise exceptions may be
14929 vectorized into a single instruction that raises each unique exception a single
14933 '``llvm.experimental.constrained.fadd``' Intrinsic
14934 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14942 @llvm.experimental.constrained.fadd(<type> <op1>, <type> <op2>,
14943 metadata <rounding mode>,
14944 metadata <exception behavior>)
14949 The '``llvm.experimental.constrained.fadd``' intrinsic returns the sum of its
14956 The first two arguments to the '``llvm.experimental.constrained.fadd``'
14957 intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
14958 of floating-point values. Both arguments must have identical types.
14960 The third and fourth arguments specify the rounding mode and exception
14961 behavior as described above.
14966 The value produced is the floating-point sum of the two value operands and has
14967 the same type as the operands.
14970 '``llvm.experimental.constrained.fsub``' Intrinsic
14971 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
14979 @llvm.experimental.constrained.fsub(<type> <op1>, <type> <op2>,
14980 metadata <rounding mode>,
14981 metadata <exception behavior>)
14986 The '``llvm.experimental.constrained.fsub``' intrinsic returns the difference
14987 of its two operands.
14993 The first two arguments to the '``llvm.experimental.constrained.fsub``'
14994 intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
14995 of floating-point values. Both arguments must have identical types.
14997 The third and fourth arguments specify the rounding mode and exception
14998 behavior as described above.
15003 The value produced is the floating-point difference of the two value operands
15004 and has the same type as the operands.
15007 '``llvm.experimental.constrained.fmul``' Intrinsic
15008 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15016 @llvm.experimental.constrained.fmul(<type> <op1>, <type> <op2>,
15017 metadata <rounding mode>,
15018 metadata <exception behavior>)
15023 The '``llvm.experimental.constrained.fmul``' intrinsic returns the product of
15030 The first two arguments to the '``llvm.experimental.constrained.fmul``'
15031 intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
15032 of floating-point values. Both arguments must have identical types.
15034 The third and fourth arguments specify the rounding mode and exception
15035 behavior as described above.
15040 The value produced is the floating-point product of the two value operands and
15041 has the same type as the operands.
15044 '``llvm.experimental.constrained.fdiv``' Intrinsic
15045 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15053 @llvm.experimental.constrained.fdiv(<type> <op1>, <type> <op2>,
15054 metadata <rounding mode>,
15055 metadata <exception behavior>)
15060 The '``llvm.experimental.constrained.fdiv``' intrinsic returns the quotient of
15067 The first two arguments to the '``llvm.experimental.constrained.fdiv``'
15068 intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
15069 of floating-point values. Both arguments must have identical types.
15071 The third and fourth arguments specify the rounding mode and exception
15072 behavior as described above.
15077 The value produced is the floating-point quotient of the two value operands and
15078 has the same type as the operands.
15081 '``llvm.experimental.constrained.frem``' Intrinsic
15082 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15090 @llvm.experimental.constrained.frem(<type> <op1>, <type> <op2>,
15091 metadata <rounding mode>,
15092 metadata <exception behavior>)
15097 The '``llvm.experimental.constrained.frem``' intrinsic returns the remainder
15098 from the division of its two operands.
15104 The first two arguments to the '``llvm.experimental.constrained.frem``'
15105 intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
15106 of floating-point values. Both arguments must have identical types.
15108 The third and fourth arguments specify the rounding mode and exception
15109 behavior as described above. The rounding mode argument has no effect, since
15110 the result of frem is never rounded, but the argument is included for
15111 consistency with the other constrained floating-point intrinsics.
15116 The value produced is the floating-point remainder from the division of the two
15117 value operands and has the same type as the operands. The remainder has the
15118 same sign as the dividend.
15120 '``llvm.experimental.constrained.fma``' Intrinsic
15121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15129 @llvm.experimental.constrained.fma(<type> <op1>, <type> <op2>, <type> <op3>,
15130 metadata <rounding mode>,
15131 metadata <exception behavior>)
15136 The '``llvm.experimental.constrained.fma``' intrinsic returns the result of a
15137 fused-multiply-add operation on its operands.
15142 The first three arguments to the '``llvm.experimental.constrained.fma``'
15143 intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector
15144 <t_vector>` of floating-point values. All arguments must have identical types.
15146 The fourth and fifth arguments specify the rounding mode and exception behavior
15147 as described above.
15152 The result produced is the product of the first two operands added to the third
15153 operand computed with infinite precision, and then rounded to the target
15156 '``llvm.experimental.constrained.fptrunc``' Intrinsic
15157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15165 @llvm.experimental.constrained.fptrunc(<type> <value>,
15166 metadata <rounding mode>,
15167 metadata <exception behavior>)
15172 The '``llvm.experimental.constrained.fptrunc``' intrinsic truncates ``value``
15178 The first argument to the '``llvm.experimental.constrained.fptrunc``'
15179 intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector
15180 <t_vector>` of floating point values. This argument must be larger in size
15183 The second and third arguments specify the rounding mode and exception
15184 behavior as described above.
15189 The result produced is a floating point value truncated to be smaller in size
15192 '``llvm.experimental.constrained.fpext``' Intrinsic
15193 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15201 @llvm.experimental.constrained.fpext(<type> <value>,
15202 metadata <exception behavior>)
15207 The '``llvm.experimental.constrained.fpext``' intrinsic extends a
15208 floating-point ``value`` to a larger floating-point value.
15213 The first argument to the '``llvm.experimental.constrained.fpext``'
15214 intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector
15215 <t_vector>` of floating point values. This argument must be smaller in size
15218 The second argument specifies the exception behavior as described above.
15223 The result produced is a floating point value extended to be larger in size
15224 than the operand. All restrictions that apply to the fpext instruction also
15225 apply to this intrinsic.
15227 Constrained libm-equivalent Intrinsics
15228 --------------------------------------
15230 In addition to the basic floating-point operations for which constrained
15231 intrinsics are described above, there are constrained versions of various
15232 operations which provide equivalent behavior to a corresponding libm function.
15233 These intrinsics allow the precise behavior of these operations with respect to
15234 rounding mode and exception behavior to be controlled.
15236 As with the basic constrained floating-point intrinsics, the rounding mode
15237 and exception behavior arguments only control the behavior of the optimizer.
15238 They do not change the runtime floating-point environment.
15241 '``llvm.experimental.constrained.sqrt``' Intrinsic
15242 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15250 @llvm.experimental.constrained.sqrt(<type> <op1>,
15251 metadata <rounding mode>,
15252 metadata <exception behavior>)
15257 The '``llvm.experimental.constrained.sqrt``' intrinsic returns the square root
15258 of the specified value, returning the same value as the libm '``sqrt``'
15259 functions would, but without setting ``errno``.
15264 The first argument and the return type are floating-point numbers of the same
15267 The second and third arguments specify the rounding mode and exception
15268 behavior as described above.
15273 This function returns the nonnegative square root of the specified value.
15274 If the value is less than negative zero, a floating-point exception occurs
15275 and the return value is architecture specific.
15278 '``llvm.experimental.constrained.pow``' Intrinsic
15279 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15287 @llvm.experimental.constrained.pow(<type> <op1>, <type> <op2>,
15288 metadata <rounding mode>,
15289 metadata <exception behavior>)
15294 The '``llvm.experimental.constrained.pow``' intrinsic returns the first operand
15295 raised to the (positive or negative) power specified by the second operand.
15300 The first two arguments and the return value are floating-point numbers of the
15301 same type. The second argument specifies the power to which the first argument
15304 The third and fourth arguments specify the rounding mode and exception
15305 behavior as described above.
15310 This function returns the first value raised to the second power,
15311 returning the same values as the libm ``pow`` functions would, and
15312 handles error conditions in the same way.
15315 '``llvm.experimental.constrained.powi``' Intrinsic
15316 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15324 @llvm.experimental.constrained.powi(<type> <op1>, i32 <op2>,
15325 metadata <rounding mode>,
15326 metadata <exception behavior>)
15331 The '``llvm.experimental.constrained.powi``' intrinsic returns the first operand
15332 raised to the (positive or negative) power specified by the second operand. The
15333 order of evaluation of multiplications is not defined. When a vector of
15334 floating-point type is used, the second argument remains a scalar integer value.
15340 The first argument and the return value are floating-point numbers of the same
15341 type. The second argument is a 32-bit signed integer specifying the power to
15342 which the first argument should be raised.
15344 The third and fourth arguments specify the rounding mode and exception
15345 behavior as described above.
15350 This function returns the first value raised to the second power with an
15351 unspecified sequence of rounding operations.
15354 '``llvm.experimental.constrained.sin``' Intrinsic
15355 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15363 @llvm.experimental.constrained.sin(<type> <op1>,
15364 metadata <rounding mode>,
15365 metadata <exception behavior>)
15370 The '``llvm.experimental.constrained.sin``' intrinsic returns the sine of the
15376 The first argument and the return type are floating-point numbers of the same
15379 The second and third arguments specify the rounding mode and exception
15380 behavior as described above.
15385 This function returns the sine of the specified operand, returning the
15386 same values as the libm ``sin`` functions would, and handles error
15387 conditions in the same way.
15390 '``llvm.experimental.constrained.cos``' Intrinsic
15391 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15399 @llvm.experimental.constrained.cos(<type> <op1>,
15400 metadata <rounding mode>,
15401 metadata <exception behavior>)
15406 The '``llvm.experimental.constrained.cos``' intrinsic returns the cosine of the
15412 The first argument and the return type are floating-point numbers of the same
15415 The second and third arguments specify the rounding mode and exception
15416 behavior as described above.
15421 This function returns the cosine of the specified operand, returning the
15422 same values as the libm ``cos`` functions would, and handles error
15423 conditions in the same way.
15426 '``llvm.experimental.constrained.exp``' Intrinsic
15427 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15435 @llvm.experimental.constrained.exp(<type> <op1>,
15436 metadata <rounding mode>,
15437 metadata <exception behavior>)
15442 The '``llvm.experimental.constrained.exp``' intrinsic computes the base-e
15443 exponential of the specified value.
15448 The first argument and the return value are floating-point numbers of the same
15451 The second and third arguments specify the rounding mode and exception
15452 behavior as described above.
15457 This function returns the same values as the libm ``exp`` functions
15458 would, and handles error conditions in the same way.
15461 '``llvm.experimental.constrained.exp2``' Intrinsic
15462 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15470 @llvm.experimental.constrained.exp2(<type> <op1>,
15471 metadata <rounding mode>,
15472 metadata <exception behavior>)
15477 The '``llvm.experimental.constrained.exp2``' intrinsic computes the base-2
15478 exponential of the specified value.
15484 The first argument and the return value are floating-point numbers of the same
15487 The second and third arguments specify the rounding mode and exception
15488 behavior as described above.
15493 This function returns the same values as the libm ``exp2`` functions
15494 would, and handles error conditions in the same way.
15497 '``llvm.experimental.constrained.log``' Intrinsic
15498 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15506 @llvm.experimental.constrained.log(<type> <op1>,
15507 metadata <rounding mode>,
15508 metadata <exception behavior>)
15513 The '``llvm.experimental.constrained.log``' intrinsic computes the base-e
15514 logarithm of the specified value.
15519 The first argument and the return value are floating-point numbers of the same
15522 The second and third arguments specify the rounding mode and exception
15523 behavior as described above.
15529 This function returns the same values as the libm ``log`` functions
15530 would, and handles error conditions in the same way.
15533 '``llvm.experimental.constrained.log10``' Intrinsic
15534 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15542 @llvm.experimental.constrained.log10(<type> <op1>,
15543 metadata <rounding mode>,
15544 metadata <exception behavior>)
15549 The '``llvm.experimental.constrained.log10``' intrinsic computes the base-10
15550 logarithm of the specified value.
15555 The first argument and the return value are floating-point numbers of the same
15558 The second and third arguments specify the rounding mode and exception
15559 behavior as described above.
15564 This function returns the same values as the libm ``log10`` functions
15565 would, and handles error conditions in the same way.
15568 '``llvm.experimental.constrained.log2``' Intrinsic
15569 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15577 @llvm.experimental.constrained.log2(<type> <op1>,
15578 metadata <rounding mode>,
15579 metadata <exception behavior>)
15584 The '``llvm.experimental.constrained.log2``' intrinsic computes the base-2
15585 logarithm of the specified value.
15590 The first argument and the return value are floating-point numbers of the same
15593 The second and third arguments specify the rounding mode and exception
15594 behavior as described above.
15599 This function returns the same values as the libm ``log2`` functions
15600 would, and handles error conditions in the same way.
15603 '``llvm.experimental.constrained.rint``' Intrinsic
15604 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15612 @llvm.experimental.constrained.rint(<type> <op1>,
15613 metadata <rounding mode>,
15614 metadata <exception behavior>)
15619 The '``llvm.experimental.constrained.rint``' intrinsic returns the first
15620 operand rounded to the nearest integer. It may raise an inexact floating-point
15621 exception if the operand is not an integer.
15626 The first argument and the return value are floating-point numbers of the same
15629 The second and third arguments specify the rounding mode and exception
15630 behavior as described above.
15635 This function returns the same values as the libm ``rint`` functions
15636 would, and handles error conditions in the same way. The rounding mode is
15637 described, not determined, by the rounding mode argument. The actual rounding
15638 mode is determined by the runtime floating-point environment. The rounding
15639 mode argument is only intended as information to the compiler.
15642 '``llvm.experimental.constrained.nearbyint``' Intrinsic
15643 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15651 @llvm.experimental.constrained.nearbyint(<type> <op1>,
15652 metadata <rounding mode>,
15653 metadata <exception behavior>)
15658 The '``llvm.experimental.constrained.nearbyint``' intrinsic returns the first
15659 operand rounded to the nearest integer. It will not raise an inexact
15660 floating-point exception if the operand is not an integer.
15666 The first argument and the return value are floating-point numbers of the same
15669 The second and third arguments specify the rounding mode and exception
15670 behavior as described above.
15675 This function returns the same values as the libm ``nearbyint`` functions
15676 would, and handles error conditions in the same way. The rounding mode is
15677 described, not determined, by the rounding mode argument. The actual rounding
15678 mode is determined by the runtime floating-point environment. The rounding
15679 mode argument is only intended as information to the compiler.
15682 '``llvm.experimental.constrained.maxnum``' Intrinsic
15683 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15691 @llvm.experimental.constrained.maxnum(<type> <op1>, <type> <op2>
15692 metadata <rounding mode>,
15693 metadata <exception behavior>)
15698 The '``llvm.experimental.constrained.maxnum``' intrinsic returns the maximum
15699 of the two arguments.
15704 The first two arguments and the return value are floating-point numbers
15707 The third and forth arguments specify the rounding mode and exception
15708 behavior as described above.
15713 This function follows the IEEE-754 semantics for maxNum. The rounding mode is
15714 described, not determined, by the rounding mode argument. The actual rounding
15715 mode is determined by the runtime floating-point environment. The rounding
15716 mode argument is only intended as information to the compiler.
15719 '``llvm.experimental.constrained.minnum``' Intrinsic
15720 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15728 @llvm.experimental.constrained.minnum(<type> <op1>, <type> <op2>
15729 metadata <rounding mode>,
15730 metadata <exception behavior>)
15735 The '``llvm.experimental.constrained.minnum``' intrinsic returns the minimum
15736 of the two arguments.
15741 The first two arguments and the return value are floating-point numbers
15744 The third and forth arguments specify the rounding mode and exception
15745 behavior as described above.
15750 This function follows the IEEE-754 semantics for minNum. The rounding mode is
15751 described, not determined, by the rounding mode argument. The actual rounding
15752 mode is determined by the runtime floating-point environment. The rounding
15753 mode argument is only intended as information to the compiler.
15756 '``llvm.experimental.constrained.ceil``' Intrinsic
15757 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15765 @llvm.experimental.constrained.ceil(<type> <op1>,
15766 metadata <rounding mode>,
15767 metadata <exception behavior>)
15772 The '``llvm.experimental.constrained.ceil``' intrinsic returns the ceiling of the
15778 The first argument and the return value are floating-point numbers of the same
15781 The second and third arguments specify the rounding mode and exception
15782 behavior as described above. The rounding mode is currently unused for this
15788 This function returns the same values as the libm ``ceil`` functions
15789 would and handles error conditions in the same way.
15792 '``llvm.experimental.constrained.floor``' Intrinsic
15793 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15801 @llvm.experimental.constrained.floor(<type> <op1>,
15802 metadata <rounding mode>,
15803 metadata <exception behavior>)
15808 The '``llvm.experimental.constrained.floor``' intrinsic returns the floor of the
15814 The first argument and the return value are floating-point numbers of the same
15817 The second and third arguments specify the rounding mode and exception
15818 behavior as described above. The rounding mode is currently unused for this
15824 This function returns the same values as the libm ``floor`` functions
15825 would and handles error conditions in the same way.
15828 '``llvm.experimental.constrained.round``' Intrinsic
15829 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15837 @llvm.experimental.constrained.round(<type> <op1>,
15838 metadata <rounding mode>,
15839 metadata <exception behavior>)
15844 The '``llvm.experimental.constrained.round``' intrinsic returns the first
15845 operand rounded to the nearest integer.
15850 The first argument and the return value are floating-point numbers of the same
15853 The second and third arguments specify the rounding mode and exception
15854 behavior as described above. The rounding mode is currently unused for this
15860 This function returns the same values as the libm ``round`` functions
15861 would and handles error conditions in the same way.
15864 '``llvm.experimental.constrained.trunc``' Intrinsic
15865 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15873 @llvm.experimental.constrained.trunc(<type> <op1>,
15874 metadata <truncing mode>,
15875 metadata <exception behavior>)
15880 The '``llvm.experimental.constrained.trunc``' intrinsic returns the first
15881 operand rounded to the nearest integer not larger in magnitude than the
15887 The first argument and the return value are floating-point numbers of the same
15890 The second and third arguments specify the truncing mode and exception
15891 behavior as described above. The truncing mode is currently unused for this
15897 This function returns the same values as the libm ``trunc`` functions
15898 would and handles error conditions in the same way.
15904 This class of intrinsics is designed to be generic and has no specific
15907 '``llvm.var.annotation``' Intrinsic
15908 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15915 declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
15920 The '``llvm.var.annotation``' intrinsic.
15925 The first argument is a pointer to a value, the second is a pointer to a
15926 global string, the third is a pointer to a global string which is the
15927 source file name, and the last argument is the line number.
15932 This intrinsic allows annotation of local variables with arbitrary
15933 strings. This can be useful for special purpose optimizations that want
15934 to look for these annotations. These have no other defined use; they are
15935 ignored by code generation and optimization.
15937 '``llvm.ptr.annotation.*``' Intrinsic
15938 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15943 This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a
15944 pointer to an integer of any width. *NOTE* you must specify an address space for
15945 the pointer. The identifier for the default address space is the integer
15950 declare i8* @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
15951 declare i16* @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32 <int>)
15952 declare i32* @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32 <int>)
15953 declare i64* @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32 <int>)
15954 declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32 <int>)
15959 The '``llvm.ptr.annotation``' intrinsic.
15964 The first argument is a pointer to an integer value of arbitrary bitwidth
15965 (result of some expression), the second is a pointer to a global string, the
15966 third is a pointer to a global string which is the source file name, and the
15967 last argument is the line number. It returns the value of the first argument.
15972 This intrinsic allows annotation of a pointer to an integer with arbitrary
15973 strings. This can be useful for special purpose optimizations that want to look
15974 for these annotations. These have no other defined use; they are ignored by code
15975 generation and optimization.
15977 '``llvm.annotation.*``' Intrinsic
15978 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15983 This is an overloaded intrinsic. You can use '``llvm.annotation``' on
15984 any integer bit width.
15988 declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>)
15989 declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>)
15990 declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>)
15991 declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>)
15992 declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>)
15997 The '``llvm.annotation``' intrinsic.
16002 The first argument is an integer value (result of some expression), the
16003 second is a pointer to a global string, the third is a pointer to a
16004 global string which is the source file name, and the last argument is
16005 the line number. It returns the value of the first argument.
16010 This intrinsic allows annotations to be put on arbitrary expressions
16011 with arbitrary strings. This can be useful for special purpose
16012 optimizations that want to look for these annotations. These have no
16013 other defined use; they are ignored by code generation and optimization.
16015 '``llvm.codeview.annotation``' Intrinsic
16016 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16021 This annotation emits a label at its program point and an associated
16022 ``S_ANNOTATION`` codeview record with some additional string metadata. This is
16023 used to implement MSVC's ``__annotation`` intrinsic. It is marked
16024 ``noduplicate``, so calls to this intrinsic prevent inlining and should be
16025 considered expensive.
16029 declare void @llvm.codeview.annotation(metadata)
16034 The argument should be an MDTuple containing any number of MDStrings.
16036 '``llvm.trap``' Intrinsic
16037 ^^^^^^^^^^^^^^^^^^^^^^^^^
16044 declare void @llvm.trap() cold noreturn nounwind
16049 The '``llvm.trap``' intrinsic.
16059 This intrinsic is lowered to the target dependent trap instruction. If
16060 the target does not have a trap instruction, this intrinsic will be
16061 lowered to a call of the ``abort()`` function.
16063 '``llvm.debugtrap``' Intrinsic
16064 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16071 declare void @llvm.debugtrap() nounwind
16076 The '``llvm.debugtrap``' intrinsic.
16086 This intrinsic is lowered to code which is intended to cause an
16087 execution trap with the intention of requesting the attention of a
16090 '``llvm.stackprotector``' Intrinsic
16091 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16098 declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
16103 The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it
16104 onto the stack at ``slot``. The stack slot is adjusted to ensure that it
16105 is placed on the stack before local variables.
16110 The ``llvm.stackprotector`` intrinsic requires two pointer arguments.
16111 The first argument is the value loaded from the stack guard
16112 ``@__stack_chk_guard``. The second variable is an ``alloca`` that has
16113 enough space to hold the value of the guard.
16118 This intrinsic causes the prologue/epilogue inserter to force the position of
16119 the ``AllocaInst`` stack slot to be before local variables on the stack. This is
16120 to ensure that if a local variable on the stack is overwritten, it will destroy
16121 the value of the guard. When the function exits, the guard on the stack is
16122 checked against the original guard by ``llvm.stackprotectorcheck``. If they are
16123 different, then ``llvm.stackprotectorcheck`` causes the program to abort by
16124 calling the ``__stack_chk_fail()`` function.
16126 '``llvm.stackguard``' Intrinsic
16127 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16134 declare i8* @llvm.stackguard()
16139 The ``llvm.stackguard`` intrinsic returns the system stack guard value.
16141 It should not be generated by frontends, since it is only for internal usage.
16142 The reason why we create this intrinsic is that we still support IR form Stack
16143 Protector in FastISel.
16153 On some platforms, the value returned by this intrinsic remains unchanged
16154 between loads in the same thread. On other platforms, it returns the same
16155 global variable value, if any, e.g. ``@__stack_chk_guard``.
16157 Currently some platforms have IR-level customized stack guard loading (e.g.
16158 X86 Linux) that is not handled by ``llvm.stackguard()``, while they should be
16161 '``llvm.objectsize``' Intrinsic
16162 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16169 declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>)
16170 declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>)
16175 The ``llvm.objectsize`` intrinsic is designed to provide information to the
16176 optimizer to determine whether a) an operation (like memcpy) will overflow a
16177 buffer that corresponds to an object, or b) that a runtime check for overflow
16178 isn't necessary. An object in this context means an allocation of a specific
16179 class, structure, array, or other object.
16184 The ``llvm.objectsize`` intrinsic takes four arguments. The first argument is a
16185 pointer to or into the ``object``. The second argument determines whether
16186 ``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size is
16187 unknown. The third argument controls how ``llvm.objectsize`` acts when ``null``
16188 in address space 0 is used as its pointer argument. If it's ``false``,
16189 ``llvm.objectsize`` reports 0 bytes available when given ``null``. Otherwise, if
16190 the ``null`` is in a non-zero address space or if ``true`` is given for the
16191 third argument of ``llvm.objectsize``, we assume its size is unknown. The fourth
16192 argument to ``llvm.objectsize`` determines if the value should be evaluated at
16195 The second, third, and fourth arguments only accept constants.
16200 The ``llvm.objectsize`` intrinsic is lowered to a value representing the size of
16201 the object concerned. If the size cannot be determined, ``llvm.objectsize``
16202 returns ``i32/i64 -1 or 0`` (depending on the ``min`` argument).
16204 '``llvm.expect``' Intrinsic
16205 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
16210 This is an overloaded intrinsic. You can use ``llvm.expect`` on any
16215 declare i1 @llvm.expect.i1(i1 <val>, i1 <expected_val>)
16216 declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
16217 declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)
16222 The ``llvm.expect`` intrinsic provides information about expected (the
16223 most probable) value of ``val``, which can be used by optimizers.
16228 The ``llvm.expect`` intrinsic takes two arguments. The first argument is
16229 a value. The second argument is an expected value.
16234 This intrinsic is lowered to the ``val``.
16238 '``llvm.assume``' Intrinsic
16239 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16246 declare void @llvm.assume(i1 %cond)
16251 The ``llvm.assume`` allows the optimizer to assume that the provided
16252 condition is true. This information can then be used in simplifying other parts
16258 The condition which the optimizer may assume is always true.
16263 The intrinsic allows the optimizer to assume that the provided condition is
16264 always true whenever the control flow reaches the intrinsic call. No code is
16265 generated for this intrinsic, and instructions that contribute only to the
16266 provided condition are not used for code generation. If the condition is
16267 violated during execution, the behavior is undefined.
16269 Note that the optimizer might limit the transformations performed on values
16270 used by the ``llvm.assume`` intrinsic in order to preserve the instructions
16271 only used to form the intrinsic's input argument. This might prove undesirable
16272 if the extra information provided by the ``llvm.assume`` intrinsic does not cause
16273 sufficient overall improvement in code quality. For this reason,
16274 ``llvm.assume`` should not be used to document basic mathematical invariants
16275 that the optimizer can otherwise deduce or facts that are of little use to the
16280 '``llvm.ssa_copy``' Intrinsic
16281 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16288 declare type @llvm.ssa_copy(type %operand) returned(1) readnone
16293 The first argument is an operand which is used as the returned value.
16298 The ``llvm.ssa_copy`` intrinsic can be used to attach information to
16299 operations by copying them and giving them new names. For example,
16300 the PredicateInfo utility uses it to build Extended SSA form, and
16301 attach various forms of information to operands that dominate specific
16302 uses. It is not meant for general use, only for building temporary
16303 renaming forms that require value splits at certain points.
16307 '``llvm.type.test``' Intrinsic
16308 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16315 declare i1 @llvm.type.test(i8* %ptr, metadata %type) nounwind readnone
16321 The first argument is a pointer to be tested. The second argument is a
16322 metadata object representing a :doc:`type identifier <TypeMetadata>`.
16327 The ``llvm.type.test`` intrinsic tests whether the given pointer is associated
16328 with the given type identifier.
16330 '``llvm.type.checked.load``' Intrinsic
16331 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16338 declare {i8*, i1} @llvm.type.checked.load(i8* %ptr, i32 %offset, metadata %type) argmemonly nounwind readonly
16344 The first argument is a pointer from which to load a function pointer. The
16345 second argument is the byte offset from which to load the function pointer. The
16346 third argument is a metadata object representing a :doc:`type identifier
16352 The ``llvm.type.checked.load`` intrinsic safely loads a function pointer from a
16353 virtual table pointer using type metadata. This intrinsic is used to implement
16354 control flow integrity in conjunction with virtual call optimization. The
16355 virtual call optimization pass will optimize away ``llvm.type.checked.load``
16356 intrinsics associated with devirtualized calls, thereby removing the type
16357 check in cases where it is not needed to enforce the control flow integrity
16360 If the given pointer is associated with a type metadata identifier, this
16361 function returns true as the second element of its return value. (Note that
16362 the function may also return true if the given pointer is not associated
16363 with a type metadata identifier.) If the function's return value's second
16364 element is true, the following rules apply to the first element:
16366 - If the given pointer is associated with the given type metadata identifier,
16367 it is the function pointer loaded from the given byte offset from the given
16370 - If the given pointer is not associated with the given type metadata
16371 identifier, it is one of the following (the choice of which is unspecified):
16373 1. The function pointer that would have been loaded from an arbitrarily chosen
16374 (through an unspecified mechanism) pointer associated with the type
16377 2. If the function has a non-void return type, a pointer to a function that
16378 returns an unspecified value without causing side effects.
16380 If the function's return value's second element is false, the value of the
16381 first element is undefined.
16384 '``llvm.donothing``' Intrinsic
16385 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16392 declare void @llvm.donothing() nounwind readnone
16397 The ``llvm.donothing`` intrinsic doesn't perform any operation. It's one of only
16398 three intrinsics (besides ``llvm.experimental.patchpoint`` and
16399 ``llvm.experimental.gc.statepoint``) that can be called with an invoke
16410 This intrinsic does nothing, and it's removed by optimizers and ignored
16413 '``llvm.experimental.deoptimize``' Intrinsic
16414 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16421 declare type @llvm.experimental.deoptimize(...) [ "deopt"(...) ]
16426 This intrinsic, together with :ref:`deoptimization operand bundles
16427 <deopt_opbundles>`, allow frontends to express transfer of control and
16428 frame-local state from the currently executing (typically more specialized,
16429 hence faster) version of a function into another (typically more generic, hence
16432 In languages with a fully integrated managed runtime like Java and JavaScript
16433 this intrinsic can be used to implement "uncommon trap" or "side exit" like
16434 functionality. In unmanaged languages like C and C++, this intrinsic can be
16435 used to represent the slow paths of specialized functions.
16441 The intrinsic takes an arbitrary number of arguments, whose meaning is
16442 decided by the :ref:`lowering strategy<deoptimize_lowering>`.
16447 The ``@llvm.experimental.deoptimize`` intrinsic executes an attached
16448 deoptimization continuation (denoted using a :ref:`deoptimization
16449 operand bundle <deopt_opbundles>`) and returns the value returned by
16450 the deoptimization continuation. Defining the semantic properties of
16451 the continuation itself is out of scope of the language reference --
16452 as far as LLVM is concerned, the deoptimization continuation can
16453 invoke arbitrary side effects, including reading from and writing to
16456 Deoptimization continuations expressed using ``"deopt"`` operand bundles always
16457 continue execution to the end of the physical frame containing them, so all
16458 calls to ``@llvm.experimental.deoptimize`` must be in "tail position":
16460 - ``@llvm.experimental.deoptimize`` cannot be invoked.
16461 - The call must immediately precede a :ref:`ret <i_ret>` instruction.
16462 - The ``ret`` instruction must return the value produced by the
16463 ``@llvm.experimental.deoptimize`` call if there is one, or void.
16465 Note that the above restrictions imply that the return type for a call to
16466 ``@llvm.experimental.deoptimize`` will match the return type of its immediate
16469 The inliner composes the ``"deopt"`` continuations of the caller into the
16470 ``"deopt"`` continuations present in the inlinee, and also updates calls to this
16471 intrinsic to return directly from the frame of the function it inlined into.
16473 All declarations of ``@llvm.experimental.deoptimize`` must share the
16474 same calling convention.
16476 .. _deoptimize_lowering:
16481 Calls to ``@llvm.experimental.deoptimize`` are lowered to calls to the
16482 symbol ``__llvm_deoptimize`` (it is the frontend's responsibility to
16483 ensure that this symbol is defined). The call arguments to
16484 ``@llvm.experimental.deoptimize`` are lowered as if they were formal
16485 arguments of the specified types, and not as varargs.
16488 '``llvm.experimental.guard``' Intrinsic
16489 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16496 declare void @llvm.experimental.guard(i1, ...) [ "deopt"(...) ]
16501 This intrinsic, together with :ref:`deoptimization operand bundles
16502 <deopt_opbundles>`, allows frontends to express guards or checks on
16503 optimistic assumptions made during compilation. The semantics of
16504 ``@llvm.experimental.guard`` is defined in terms of
16505 ``@llvm.experimental.deoptimize`` -- its body is defined to be
16508 .. code-block:: text
16510 define void @llvm.experimental.guard(i1 %pred, <args...>) {
16511 %realPred = and i1 %pred, undef
16512 br i1 %realPred, label %continue, label %leave [, !make.implicit !{}]
16515 call void @llvm.experimental.deoptimize(<args...>) [ "deopt"() ]
16523 with the optional ``[, !make.implicit !{}]`` present if and only if it
16524 is present on the call site. For more details on ``!make.implicit``,
16525 see :doc:`FaultMaps`.
16527 In words, ``@llvm.experimental.guard`` executes the attached
16528 ``"deopt"`` continuation if (but **not** only if) its first argument
16529 is ``false``. Since the optimizer is allowed to replace the ``undef``
16530 with an arbitrary value, it can optimize guard to fail "spuriously",
16531 i.e. without the original condition being false (hence the "not only
16532 if"); and this allows for "check widening" type optimizations.
16534 ``@llvm.experimental.guard`` cannot be invoked.
16537 '``llvm.experimental.widenable.condition``' Intrinsic
16538 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16545 declare i1 @llvm.experimental.widenable.condition()
16550 This intrinsic represents a "widenable condition" which is
16551 boolean expressions with the following property: whether this
16552 expression is `true` or `false`, the program is correct and
16555 Together with :ref:`deoptimization operand bundles <deopt_opbundles>`,
16556 ``@llvm.experimental.widenable.condition`` allows frontends to
16557 express guards or checks on optimistic assumptions made during
16558 compilation and represent them as branch instructions on special
16561 While this may appear similar in semantics to `undef`, it is very
16562 different in that an invocation produces a particular, singular
16563 value. It is also intended to be lowered late, and remain available
16564 for specific optimizations and transforms that can benefit from its
16565 special properties.
16575 The intrinsic ``@llvm.experimental.widenable.condition()``
16576 returns either `true` or `false`. For each evaluation of a call
16577 to this intrinsic, the program must be valid and correct both if
16578 it returns `true` and if it returns `false`. This allows
16579 transformation passes to replace evaluations of this intrinsic
16580 with either value whenever one is beneficial.
16582 When used in a branch condition, it allows us to choose between
16583 two alternative correct solutions for the same problem, like
16586 .. code-block:: text
16588 %cond = call i1 @llvm.experimental.widenable.condition()
16589 br i1 %cond, label %solution_1, label %solution_2
16592 ; Apply memory-consuming but fast solution for a task.
16595 ; Cheap in memory but slow solution.
16597 Whether the result of intrinsic's call is `true` or `false`,
16598 it should be correct to pick either solution. We can switch
16599 between them by replacing the result of
16600 ``@llvm.experimental.widenable.condition`` with different
16603 This is how it can be used to represent guards as widenable branches:
16605 .. code-block:: text
16608 ; Unguarded instructions
16609 call void @llvm.experimental.guard(i1 %cond, <args...>) ["deopt"(<deopt_args...>)]
16610 ; Guarded instructions
16612 Can be expressed in an alternative equivalent form of explicit branch using
16613 ``@llvm.experimental.widenable.condition``:
16615 .. code-block:: text
16618 ; Unguarded instructions
16619 %widenable_condition = call i1 @llvm.experimental.widenable.condition()
16620 %guard_condition = and i1 %cond, %widenable_condition
16621 br i1 %guard_condition, label %guarded, label %deopt
16624 ; Guarded instructions
16627 call type @llvm.experimental.deoptimize(<args...>) [ "deopt"(<deopt_args...>) ]
16629 So the block `guarded` is only reachable when `%cond` is `true`,
16630 and it should be valid to go to the block `deopt` whenever `%cond`
16631 is `true` or `false`.
16633 ``@llvm.experimental.widenable.condition`` will never throw, thus
16634 it cannot be invoked.
16639 When ``@llvm.experimental.widenable.condition()`` is used in
16640 condition of a guard represented as explicit branch, it is
16641 legal to widen the guard's condition with any additional
16644 Guard widening looks like replacement of
16646 .. code-block:: text
16648 %widenable_cond = call i1 @llvm.experimental.widenable.condition()
16649 %guard_cond = and i1 %cond, %widenable_cond
16650 br i1 %guard_cond, label %guarded, label %deopt
16654 .. code-block:: text
16656 %widenable_cond = call i1 @llvm.experimental.widenable.condition()
16657 %new_cond = and i1 %any_other_cond, %widenable_cond
16658 %new_guard_cond = and i1 %cond, %new_cond
16659 br i1 %new_guard_cond, label %guarded, label %deopt
16661 for this branch. Here `%any_other_cond` is an arbitrarily chosen
16662 well-defined `i1` value. By making guard widening, we may
16663 impose stricter conditions on `guarded` block and bail to the
16664 deopt when the new condition is not met.
16669 Default lowering strategy is replacing the result of
16670 call of ``@llvm.experimental.widenable.condition`` with
16671 constant `true`. However it is always correct to replace
16672 it with any other `i1` value. Any pass can
16673 freely do it if it can benefit from non-default lowering.
16676 '``llvm.load.relative``' Intrinsic
16677 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16684 declare i8* @llvm.load.relative.iN(i8* %ptr, iN %offset) argmemonly nounwind readonly
16689 This intrinsic loads a 32-bit value from the address ``%ptr + %offset``,
16690 adds ``%ptr`` to that value and returns it. The constant folder specifically
16691 recognizes the form of this intrinsic and the constant initializers it may
16692 load from; if a loaded constant initializer is known to have the form
16693 ``i32 trunc(x - %ptr)``, the intrinsic call is folded to ``x``.
16695 LLVM provides that the calculation of such a constant initializer will
16696 not overflow at link time under the medium code model if ``x`` is an
16697 ``unnamed_addr`` function. However, it does not provide this guarantee for
16698 a constant initializer folded into a function body. This intrinsic can be
16699 used to avoid the possibility of overflows when loading from such a constant.
16701 '``llvm.sideeffect``' Intrinsic
16702 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16709 declare void @llvm.sideeffect() inaccessiblememonly nounwind
16714 The ``llvm.sideeffect`` intrinsic doesn't perform any operation. Optimizers
16715 treat it as having side effects, so it can be inserted into a loop to
16716 indicate that the loop shouldn't be assumed to terminate (which could
16717 potentially lead to the loop being optimized away entirely), even if it's
16718 an infinite loop with no other side effects.
16728 This intrinsic actually does nothing, but optimizers must assume that it
16729 has externally observable side effects.
16731 '``llvm.is.constant.*``' Intrinsic
16732 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16737 This is an overloaded intrinsic. You can use llvm.is.constant with any argument type.
16741 declare i1 @llvm.is.constant.i32(i32 %operand) nounwind readnone
16742 declare i1 @llvm.is.constant.f32(float %operand) nounwind readnone
16743 declare i1 @llvm.is.constant.TYPENAME(TYPE %operand) nounwind readnone
16748 The '``llvm.is.constant``' intrinsic will return true if the argument
16749 is known to be a manifest compile-time constant. It is guaranteed to
16750 fold to either true or false before generating machine code.
16755 This intrinsic generates no code. If its argument is known to be a
16756 manifest compile-time constant value, then the intrinsic will be
16757 converted to a constant true value. Otherwise, it will be converted to
16758 a constant false value.
16760 In particular, note that if the argument is a constant expression
16761 which refers to a global (the address of which _is_ a constant, but
16762 not manifest during the compile), then the intrinsic evaluates to
16765 The result also intentionally depends on the result of optimization
16766 passes -- e.g., the result can change depending on whether a
16767 function gets inlined or not. A function's parameters are
16768 obviously not constant. However, a call like
16769 ``llvm.is.constant.i32(i32 %param)`` *can* return true after the
16770 function is inlined, if the value passed to the function parameter was
16773 On the other hand, if constant folding is not run, it will never
16774 evaluate to true, even in simple cases.
16776 Stack Map Intrinsics
16777 --------------------
16779 LLVM provides experimental intrinsics to support runtime patching
16780 mechanisms commonly desired in dynamic language JITs. These intrinsics
16781 are described in :doc:`StackMaps`.
16783 Element Wise Atomic Memory Intrinsics
16784 -------------------------------------
16786 These intrinsics are similar to the standard library memory intrinsics except
16787 that they perform memory transfer as a sequence of atomic memory accesses.
16789 .. _int_memcpy_element_unordered_atomic:
16791 '``llvm.memcpy.element.unordered.atomic``' Intrinsic
16792 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16797 This is an overloaded intrinsic. You can use ``llvm.memcpy.element.unordered.atomic`` on
16798 any integer bit width and for different address spaces. Not all targets
16799 support all bit widths however.
16803 declare void @llvm.memcpy.element.unordered.atomic.p0i8.p0i8.i32(i8* <dest>,
16806 i32 <element_size>)
16807 declare void @llvm.memcpy.element.unordered.atomic.p0i8.p0i8.i64(i8* <dest>,
16810 i32 <element_size>)
16815 The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic is a specialization of the
16816 '``llvm.memcpy.*``' intrinsic. It differs in that the ``dest`` and ``src`` are treated
16817 as arrays with elements that are exactly ``element_size`` bytes, and the copy between
16818 buffers uses a sequence of :ref:`unordered atomic <ordering>` load/store operations
16819 that are a positive integer multiple of the ``element_size`` in size.
16824 The first three arguments are the same as they are in the :ref:`@llvm.memcpy <int_memcpy>`
16825 intrinsic, with the added constraint that ``len`` is required to be a positive integer
16826 multiple of the ``element_size``. If ``len`` is not a positive integer multiple of
16827 ``element_size``, then the behaviour of the intrinsic is undefined.
16829 ``element_size`` must be a compile-time constant positive power of two no greater than
16830 target-specific atomic access size limit.
16832 For each of the input pointers ``align`` parameter attribute must be specified. It
16833 must be a power of two no less than the ``element_size``. Caller guarantees that
16834 both the source and destination pointers are aligned to that boundary.
16839 The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic copies ``len`` bytes of
16840 memory from the source location to the destination location. These locations are not
16841 allowed to overlap. The memory copy is performed as a sequence of load/store operations
16842 where each access is guaranteed to be a multiple of ``element_size`` bytes wide and
16843 aligned at an ``element_size`` boundary.
16845 The order of the copy is unspecified. The same value may be read from the source
16846 buffer many times, but only one write is issued to the destination buffer per
16847 element. It is well defined to have concurrent reads and writes to both source and
16848 destination provided those reads and writes are unordered atomic when specified.
16850 This intrinsic does not provide any additional ordering guarantees over those
16851 provided by a set of unordered loads from the source location and stores to the
16857 In the most general case call to the '``llvm.memcpy.element.unordered.atomic.*``' is
16858 lowered to a call to the symbol ``__llvm_memcpy_element_unordered_atomic_*``. Where '*'
16859 is replaced with an actual element size.
16861 Optimizer is allowed to inline memory copy when it's profitable to do so.
16863 '``llvm.memmove.element.unordered.atomic``' Intrinsic
16864 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16869 This is an overloaded intrinsic. You can use
16870 ``llvm.memmove.element.unordered.atomic`` on any integer bit width and for
16871 different address spaces. Not all targets support all bit widths however.
16875 declare void @llvm.memmove.element.unordered.atomic.p0i8.p0i8.i32(i8* <dest>,
16878 i32 <element_size>)
16879 declare void @llvm.memmove.element.unordered.atomic.p0i8.p0i8.i64(i8* <dest>,
16882 i32 <element_size>)
16887 The '``llvm.memmove.element.unordered.atomic.*``' intrinsic is a specialization
16888 of the '``llvm.memmove.*``' intrinsic. It differs in that the ``dest`` and
16889 ``src`` are treated as arrays with elements that are exactly ``element_size``
16890 bytes, and the copy between buffers uses a sequence of
16891 :ref:`unordered atomic <ordering>` load/store operations that are a positive
16892 integer multiple of the ``element_size`` in size.
16897 The first three arguments are the same as they are in the
16898 :ref:`@llvm.memmove <int_memmove>` intrinsic, with the added constraint that
16899 ``len`` is required to be a positive integer multiple of the ``element_size``.
16900 If ``len`` is not a positive integer multiple of ``element_size``, then the
16901 behaviour of the intrinsic is undefined.
16903 ``element_size`` must be a compile-time constant positive power of two no
16904 greater than a target-specific atomic access size limit.
16906 For each of the input pointers the ``align`` parameter attribute must be
16907 specified. It must be a power of two no less than the ``element_size``. Caller
16908 guarantees that both the source and destination pointers are aligned to that
16914 The '``llvm.memmove.element.unordered.atomic.*``' intrinsic copies ``len`` bytes
16915 of memory from the source location to the destination location. These locations
16916 are allowed to overlap. The memory copy is performed as a sequence of load/store
16917 operations where each access is guaranteed to be a multiple of ``element_size``
16918 bytes wide and aligned at an ``element_size`` boundary.
16920 The order of the copy is unspecified. The same value may be read from the source
16921 buffer many times, but only one write is issued to the destination buffer per
16922 element. It is well defined to have concurrent reads and writes to both source
16923 and destination provided those reads and writes are unordered atomic when
16926 This intrinsic does not provide any additional ordering guarantees over those
16927 provided by a set of unordered loads from the source location and stores to the
16933 In the most general case call to the
16934 '``llvm.memmove.element.unordered.atomic.*``' is lowered to a call to the symbol
16935 ``__llvm_memmove_element_unordered_atomic_*``. Where '*' is replaced with an
16936 actual element size.
16938 The optimizer is allowed to inline the memory copy when it's profitable to do so.
16940 .. _int_memset_element_unordered_atomic:
16942 '``llvm.memset.element.unordered.atomic``' Intrinsic
16943 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16948 This is an overloaded intrinsic. You can use ``llvm.memset.element.unordered.atomic`` on
16949 any integer bit width and for different address spaces. Not all targets
16950 support all bit widths however.
16954 declare void @llvm.memset.element.unordered.atomic.p0i8.i32(i8* <dest>,
16957 i32 <element_size>)
16958 declare void @llvm.memset.element.unordered.atomic.p0i8.i64(i8* <dest>,
16961 i32 <element_size>)
16966 The '``llvm.memset.element.unordered.atomic.*``' intrinsic is a specialization of the
16967 '``llvm.memset.*``' intrinsic. It differs in that the ``dest`` is treated as an array
16968 with elements that are exactly ``element_size`` bytes, and the assignment to that array
16969 uses uses a sequence of :ref:`unordered atomic <ordering>` store operations
16970 that are a positive integer multiple of the ``element_size`` in size.
16975 The first three arguments are the same as they are in the :ref:`@llvm.memset <int_memset>`
16976 intrinsic, with the added constraint that ``len`` is required to be a positive integer
16977 multiple of the ``element_size``. If ``len`` is not a positive integer multiple of
16978 ``element_size``, then the behaviour of the intrinsic is undefined.
16980 ``element_size`` must be a compile-time constant positive power of two no greater than
16981 target-specific atomic access size limit.
16983 The ``dest`` input pointer must have the ``align`` parameter attribute specified. It
16984 must be a power of two no less than the ``element_size``. Caller guarantees that
16985 the destination pointer is aligned to that boundary.
16990 The '``llvm.memset.element.unordered.atomic.*``' intrinsic sets the ``len`` bytes of
16991 memory starting at the destination location to the given ``value``. The memory is
16992 set with a sequence of store operations where each access is guaranteed to be a
16993 multiple of ``element_size`` bytes wide and aligned at an ``element_size`` boundary.
16995 The order of the assignment is unspecified. Only one write is issued to the
16996 destination buffer per element. It is well defined to have concurrent reads and
16997 writes to the destination provided those reads and writes are unordered atomic
17000 This intrinsic does not provide any additional ordering guarantees over those
17001 provided by a set of unordered stores to the destination.
17006 In the most general case call to the '``llvm.memset.element.unordered.atomic.*``' is
17007 lowered to a call to the symbol ``__llvm_memset_element_unordered_atomic_*``. Where '*'
17008 is replaced with an actual element size.
17010 The optimizer is allowed to inline the memory assignment when it's profitable to do so.
17012 Objective-C ARC Runtime Intrinsics
17013 ----------------------------------
17015 LLVM provides intrinsics that lower to Objective-C ARC runtime entry points.
17016 LLVM is aware of the semantics of these functions, and optimizes based on that
17017 knowledge. You can read more about the details of Objective-C ARC `here
17018 <https://clang.llvm.org/docs/AutomaticReferenceCounting.html>`_.
17020 '``llvm.objc.autorelease``' Intrinsic
17021 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17027 declare i8* @llvm.objc.autorelease(i8*)
17032 Lowers to a call to `objc_autorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autorelease>`_.
17034 '``llvm.objc.autoreleasePoolPop``' Intrinsic
17035 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17041 declare void @llvm.objc.autoreleasePoolPop(i8*)
17046 Lowers to a call to `objc_autoreleasePoolPop <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpop-void-pool>`_.
17048 '``llvm.objc.autoreleasePoolPush``' Intrinsic
17049 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17055 declare i8* @llvm.objc.autoreleasePoolPush()
17060 Lowers to a call to `objc_autoreleasePoolPush <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpush-void>`_.
17062 '``llvm.objc.autoreleaseReturnValue``' Intrinsic
17063 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17069 declare i8* @llvm.objc.autoreleaseReturnValue(i8*)
17074 Lowers to a call to `objc_autoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autoreleasereturnvalue>`_.
17076 '``llvm.objc.copyWeak``' Intrinsic
17077 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17083 declare void @llvm.objc.copyWeak(i8**, i8**)
17088 Lowers to a call to `objc_copyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-copyweak-id-dest-id-src>`_.
17090 '``llvm.objc.destroyWeak``' Intrinsic
17091 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17097 declare void @llvm.objc.destroyWeak(i8**)
17102 Lowers to a call to `objc_destroyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-destroyweak-id-object>`_.
17104 '``llvm.objc.initWeak``' Intrinsic
17105 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17111 declare i8* @llvm.objc.initWeak(i8**, i8*)
17116 Lowers to a call to `objc_initWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-initweak>`_.
17118 '``llvm.objc.loadWeak``' Intrinsic
17119 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17125 declare i8* @llvm.objc.loadWeak(i8**)
17130 Lowers to a call to `objc_loadWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweak>`_.
17132 '``llvm.objc.loadWeakRetained``' Intrinsic
17133 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17139 declare i8* @llvm.objc.loadWeakRetained(i8**)
17144 Lowers to a call to `objc_loadWeakRetained <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweakretained>`_.
17146 '``llvm.objc.moveWeak``' Intrinsic
17147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17153 declare void @llvm.objc.moveWeak(i8**, i8**)
17158 Lowers to a call to `objc_moveWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-moveweak-id-dest-id-src>`_.
17160 '``llvm.objc.release``' Intrinsic
17161 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17167 declare void @llvm.objc.release(i8*)
17172 Lowers to a call to `objc_release <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-release-id-value>`_.
17174 '``llvm.objc.retain``' Intrinsic
17175 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17181 declare i8* @llvm.objc.retain(i8*)
17186 Lowers to a call to `objc_retain <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retain>`_.
17188 '``llvm.objc.retainAutorelease``' Intrinsic
17189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17195 declare i8* @llvm.objc.retainAutorelease(i8*)
17200 Lowers to a call to `objc_retainAutorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautorelease>`_.
17202 '``llvm.objc.retainAutoreleaseReturnValue``' Intrinsic
17203 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17209 declare i8* @llvm.objc.retainAutoreleaseReturnValue(i8*)
17214 Lowers to a call to `objc_retainAutoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasereturnvalue>`_.
17216 '``llvm.objc.retainAutoreleasedReturnValue``' Intrinsic
17217 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17223 declare i8* @llvm.objc.retainAutoreleasedReturnValue(i8*)
17228 Lowers to a call to `objc_retainAutoreleasedReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasedreturnvalue>`_.
17230 '``llvm.objc.retainBlock``' Intrinsic
17231 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17237 declare i8* @llvm.objc.retainBlock(i8*)
17242 Lowers to a call to `objc_retainBlock <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainblock>`_.
17244 '``llvm.objc.storeStrong``' Intrinsic
17245 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17251 declare void @llvm.objc.storeStrong(i8**, i8*)
17256 Lowers to a call to `objc_storeStrong <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-storestrong-id-object-id-value>`_.
17258 '``llvm.objc.storeWeak``' Intrinsic
17259 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17265 declare i8* @llvm.objc.storeWeak(i8**, i8*)
17270 Lowers to a call to `objc_storeWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-storeweak>`_.