Add a paragraph on prefix data layout.
[oota-llvm.git] / docs / LangRef.rst
1 ==============================
2 LLVM Language Reference Manual
3 ==============================
4
5 .. contents::
6    :local:
7    :depth: 3
8
9 Abstract
10 ========
11
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
17 strategy.
18
19 Introduction
20 ============
21
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.
31
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.
42
43 .. _wellformed:
44
45 Well-Formedness
46 ---------------
47
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:
52
53 .. code-block:: llvm
54
55     %x = add i32 1, %x
56
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.
63
64 .. _identifiers:
65
66 Identifiers
67 ===========
68
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:
74
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 which 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.
83 #. Unnamed values are represented as an unsigned numeric value with
84    their prefix. For example, ``%12``, ``@2``, ``%44``.
85 #. Constants, which are described in the section  Constants_ below.
86
87 LLVM requires that values start with a prefix for two reasons: Compilers
88 don't need to worry about name clashes with reserved words, and the set
89 of reserved words may be expanded in the future without penalty.
90 Additionally, unnamed identifiers allow a compiler to quickly come up
91 with a temporary variable without having to avoid symbol table
92 conflicts.
93
94 Reserved words in LLVM are very similar to reserved words in other
95 languages. There are keywords for different opcodes ('``add``',
96 '``bitcast``', '``ret``', etc...), for primitive type names ('``void``',
97 '``i32``', etc...), and others. These reserved words cannot conflict
98 with variable names, because none of them start with a prefix character
99 (``'%'`` or ``'@'``).
100
101 Here is an example of LLVM code to multiply the integer variable
102 '``%X``' by 8:
103
104 The easy way:
105
106 .. code-block:: llvm
107
108     %result = mul i32 %X, 8
109
110 After strength reduction:
111
112 .. code-block:: llvm
113
114     %result = shl i32 %X, 3
115
116 And the hard way:
117
118 .. code-block:: llvm
119
120     %0 = add i32 %X, %X           ; yields {i32}:%0
121     %1 = add i32 %0, %0           ; yields {i32}:%1
122     %result = add i32 %1, %1
123
124 This last way of multiplying ``%X`` by 8 illustrates several important
125 lexical features of LLVM:
126
127 #. Comments are delimited with a '``;``' and go until the end of line.
128 #. Unnamed temporaries are created when the result of a computation is
129    not assigned to a named value.
130 #. Unnamed temporaries are numbered sequentially (using a per-function
131    incrementing counter, starting with 0).
132
133 It also shows a convention that we follow in this document. When
134 demonstrating instructions, we will follow an instruction with a comment
135 that defines the type and name of value produced.
136
137 High Level Structure
138 ====================
139
140 Module Structure
141 ----------------
142
143 LLVM programs are composed of ``Module``'s, each of which is a
144 translation unit of the input programs. Each module consists of
145 functions, global variables, and symbol table entries. Modules may be
146 combined together with the LLVM linker, which merges function (and
147 global variable) definitions, resolves forward declarations, and merges
148 symbol table entries. Here is an example of the "hello world" module:
149
150 .. code-block:: llvm
151
152     ; Declare the string constant as a global constant.
153     @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
154
155     ; External declaration of the puts function
156     declare i32 @puts(i8* nocapture) nounwind
157
158     ; Definition of main function
159     define i32 @main() {   ; i32()*
160       ; Convert [13 x i8]* to i8  *...
161       %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0
162
163       ; Call puts function to write out the string to stdout.
164       call i32 @puts(i8* %cast210)
165       ret i32 0
166     }
167
168     ; Named metadata
169     !1 = metadata !{i32 42}
170     !foo = !{!1, null}
171
172 This example is made up of a :ref:`global variable <globalvars>` named
173 "``.str``", an external declaration of the "``puts``" function, a
174 :ref:`function definition <functionstructure>` for "``main``" and
175 :ref:`named metadata <namedmetadatastructure>` "``foo``".
176
177 In general, a module is made up of a list of global values (where both
178 functions and global variables are global values). Global values are
179 represented by a pointer to a memory location (in this case, a pointer
180 to an array of char, and a pointer to a function), and have one of the
181 following :ref:`linkage types <linkage>`.
182
183 .. _linkage:
184
185 Linkage Types
186 -------------
187
188 All Global Variables and Functions have one of the following types of
189 linkage:
190
191 ``private``
192     Global values with "``private``" linkage are only directly
193     accessible by objects in the current module. In particular, linking
194     code into a module with an private global value may cause the
195     private to be renamed as necessary to avoid collisions. Because the
196     symbol is private to the module, all references can be updated. This
197     doesn't show up in any symbol table in the object file.
198 ``linker_private``
199     Similar to ``private``, but the symbol is passed through the
200     assembler and evaluated by the linker. Unlike normal strong symbols,
201     they are removed by the linker from the final linked image
202     (executable or dynamic library).
203 ``linker_private_weak``
204     Similar to "``linker_private``", but the symbol is weak. Note that
205     ``linker_private_weak`` symbols are subject to coalescing by the
206     linker. The symbols are removed by the linker from the final linked
207     image (executable or dynamic library).
208 ``internal``
209     Similar to private, but the value shows as a local symbol
210     (``STB_LOCAL`` in the case of ELF) in the object file. This
211     corresponds to the notion of the '``static``' keyword in C.
212 ``available_externally``
213     Globals with "``available_externally``" linkage are never emitted
214     into the object file corresponding to the LLVM module. They exist to
215     allow inlining and other optimizations to take place given knowledge
216     of the definition of the global, which is known to be somewhere
217     outside the module. Globals with ``available_externally`` linkage
218     are allowed to be discarded at will, and are otherwise the same as
219     ``linkonce_odr``. This linkage type is only allowed on definitions,
220     not declarations.
221 ``linkonce``
222     Globals with "``linkonce``" linkage are merged with other globals of
223     the same name when linkage occurs. This can be used to implement
224     some forms of inline functions, templates, or other code which must
225     be generated in each translation unit that uses it, but where the
226     body may be overridden with a more definitive definition later.
227     Unreferenced ``linkonce`` globals are allowed to be discarded. Note
228     that ``linkonce`` linkage does not actually allow the optimizer to
229     inline the body of this function into callers because it doesn't
230     know if this definition of the function is the definitive definition
231     within the program or whether it will be overridden by a stronger
232     definition. To enable inlining and other optimizations, use
233     "``linkonce_odr``" linkage.
234 ``weak``
235     "``weak``" linkage has the same merging semantics as ``linkonce``
236     linkage, except that unreferenced globals with ``weak`` linkage may
237     not be discarded. This is used for globals that are declared "weak"
238     in C source code.
239 ``common``
240     "``common``" linkage is most similar to "``weak``" linkage, but they
241     are used for tentative definitions in C, such as "``int X;``" at
242     global scope. Symbols with "``common``" linkage are merged in the
243     same way as ``weak symbols``, and they may not be deleted if
244     unreferenced. ``common`` symbols may not have an explicit section,
245     must have a zero initializer, and may not be marked
246     ':ref:`constant <globalvars>`'. Functions and aliases may not have
247     common linkage.
248
249 .. _linkage_appending:
250
251 ``appending``
252     "``appending``" linkage may only be applied to global variables of
253     pointer to array type. When two global variables with appending
254     linkage are linked together, the two global arrays are appended
255     together. This is the LLVM, typesafe, equivalent of having the
256     system linker append together "sections" with identical names when
257     .o files are linked.
258 ``extern_weak``
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.
270 ``linkonce_odr_auto_hide``
271     Similar to "``linkonce_odr``", but nothing in the translation unit
272     takes the address of this definition. For instance, functions that
273     had an inline definition, but the compiler decided not to inline it.
274     ``linkonce_odr_auto_hide`` may have only ``default`` visibility. The
275     symbols are removed by the linker from the final linked image
276     (executable or dynamic library).
277 ``external``
278     If none of the above identifiers are used, the global is externally
279     visible, meaning that it participates in linkage and can be used to
280     resolve external symbol references.
281
282 The next two types of linkage are targeted for Microsoft Windows
283 platform only. They are designed to support importing (exporting)
284 symbols from (to) DLLs (Dynamic Link Libraries).
285
286 ``dllimport``
287     "``dllimport``" linkage causes the compiler to reference a function
288     or variable via a global pointer to a pointer that is set up by the
289     DLL exporting the symbol. On Microsoft Windows targets, the pointer
290     name is formed by combining ``__imp_`` and the function or variable
291     name.
292 ``dllexport``
293     "``dllexport``" linkage causes the compiler to provide a global
294     pointer to a pointer in a DLL, so that it can be referenced with the
295     ``dllimport`` attribute. On Microsoft Windows targets, the pointer
296     name is formed by combining ``__imp_`` and the function or variable
297     name.
298
299 For example, since the "``.LC0``" variable is defined to be internal, if
300 another module defined a "``.LC0``" variable and was linked with this
301 one, one of the two would be renamed, preventing a collision. Since
302 "``main``" and "``puts``" are external (i.e., lacking any linkage
303 declarations), they are accessible outside of the current module.
304
305 It is illegal for a function *declaration* to have any linkage type
306 other than ``external``, ``dllimport`` or ``extern_weak``.
307
308 Aliases can have only ``external``, ``internal``, ``weak`` or
309 ``weak_odr`` linkages.
310
311 .. _callingconv:
312
313 Calling Conventions
314 -------------------
315
316 LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and
317 :ref:`invokes <i_invoke>` can all have an optional calling convention
318 specified for the call. The calling convention of any pair of dynamic
319 caller/callee must match, or the behavior of the program is undefined.
320 The following calling conventions are supported by LLVM, and more may be
321 added in the future:
322
323 "``ccc``" - The C calling convention
324     This calling convention (the default if no other calling convention
325     is specified) matches the target C calling conventions. This calling
326     convention supports varargs function calls and tolerates some
327     mismatch in the declared prototype and implemented declaration of
328     the function (as does normal C).
329 "``fastcc``" - The fast calling convention
330     This calling convention attempts to make calls as fast as possible
331     (e.g. by passing things in registers). This calling convention
332     allows the target to use whatever tricks it wants to produce fast
333     code for the target, without having to conform to an externally
334     specified ABI (Application Binary Interface). `Tail calls can only
335     be optimized when this, the GHC or the HiPE convention is
336     used. <CodeGenerator.html#id80>`_ This calling convention does not
337     support varargs and requires the prototype of all callees to exactly
338     match the prototype of the function definition.
339 "``coldcc``" - The cold calling convention
340     This calling convention attempts to make code in the caller as
341     efficient as possible under the assumption that the call is not
342     commonly executed. As such, these calls often preserve all registers
343     so that the call does not break any live ranges in the caller side.
344     This calling convention does not support varargs and requires the
345     prototype of all callees to exactly match the prototype of the
346     function definition.
347 "``cc 10``" - GHC convention
348     This calling convention has been implemented specifically for use by
349     the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_.
350     It passes everything in registers, going to extremes to achieve this
351     by disabling callee save registers. This calling convention should
352     not be used lightly but only for specific situations such as an
353     alternative to the *register pinning* performance technique often
354     used when implementing functional programming languages. At the
355     moment only X86 supports this convention and it has the following
356     limitations:
357
358     -  On *X86-32* only supports up to 4 bit type parameters. No
359        floating point types are supported.
360     -  On *X86-64* only supports up to 10 bit type parameters and 6
361        floating point parameters.
362
363     This calling convention supports `tail call
364     optimization <CodeGenerator.html#id80>`_ but requires both the
365     caller and callee are using it.
366 "``cc 11``" - The HiPE calling convention
367     This calling convention has been implemented specifically for use by
368     the `High-Performance Erlang
369     (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the*
370     native code compiler of the `Ericsson's Open Source Erlang/OTP
371     system <http://www.erlang.org/download.shtml>`_. It uses more
372     registers for argument passing than the ordinary C calling
373     convention and defines no callee-saved registers. The calling
374     convention properly supports `tail call
375     optimization <CodeGenerator.html#id80>`_ but requires that both the
376     caller and the callee use it. It uses a *register pinning*
377     mechanism, similar to GHC's convention, for keeping frequently
378     accessed runtime components pinned to specific hardware registers.
379     At the moment only X86 supports this convention (both 32 and 64
380     bit).
381 "``cc <n>``" - Numbered convention
382     Any calling convention may be specified by number, allowing
383     target-specific calling conventions to be used. Target specific
384     calling conventions start at 64.
385
386 More calling conventions can be added/defined on an as-needed basis, to
387 support Pascal conventions or any other well-known target-independent
388 convention.
389
390 .. _visibilitystyles:
391
392 Visibility Styles
393 -----------------
394
395 All Global Variables and Functions have one of the following visibility
396 styles:
397
398 "``default``" - Default style
399     On targets that use the ELF object file format, default visibility
400     means that the declaration is visible to other modules and, in
401     shared libraries, means that the declared entity may be overridden.
402     On Darwin, default visibility means that the declaration is visible
403     to other modules. Default visibility corresponds to "external
404     linkage" in the language.
405 "``hidden``" - Hidden style
406     Two declarations of an object with hidden visibility refer to the
407     same object if they are in the same shared object. Usually, hidden
408     visibility indicates that the symbol will not be placed into the
409     dynamic symbol table, so no other module (executable or shared
410     library) can reference it directly.
411 "``protected``" - Protected style
412     On ELF, protected visibility indicates that the symbol will be
413     placed in the dynamic symbol table, but that references within the
414     defining module will bind to the local symbol. That is, the symbol
415     cannot be overridden by another module.
416
417 .. _namedtypes:
418
419 Named Types
420 -----------
421
422 LLVM IR allows you to specify name aliases for certain types. This can
423 make it easier to read the IR and make the IR more condensed
424 (particularly when recursive types are involved). An example of a name
425 specification is:
426
427 .. code-block:: llvm
428
429     %mytype = type { %mytype*, i32 }
430
431 You may give a name to any :ref:`type <typesystem>` except
432 ":ref:`void <t_void>`". Type name aliases may be used anywhere a type is
433 expected with the syntax "%mytype".
434
435 Note that type names are aliases for the structural type that they
436 indicate, and that you can therefore specify multiple names for the same
437 type. This often leads to confusing behavior when dumping out a .ll
438 file. Since LLVM IR uses structural typing, the name is not part of the
439 type. When printing out LLVM IR, the printer will pick *one name* to
440 render all types of a particular shape. This means that if you have code
441 where two different source types end up having the same LLVM type, that
442 the dumper will sometimes print the "wrong" or unexpected type. This is
443 an important design point and isn't going to change.
444
445 .. _globalvars:
446
447 Global Variables
448 ----------------
449
450 Global variables define regions of memory allocated at compilation time
451 instead of run-time. Global variables may optionally be initialized, may
452 have an explicit section to be placed in, and may have an optional
453 explicit alignment specified.
454
455 A variable may be defined as ``thread_local``, which means that it will
456 not be shared by threads (each thread will have a separated copy of the
457 variable). Not all targets support thread-local variables. Optionally, a
458 TLS model may be specified:
459
460 ``localdynamic``
461     For variables that are only used within the current shared library.
462 ``initialexec``
463     For variables in modules that will not be loaded dynamically.
464 ``localexec``
465     For variables defined in the executable and only used within it.
466
467 The models correspond to the ELF TLS models; see `ELF Handling For
468 Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for
469 more information on under which circumstances the different models may
470 be used. The target may choose a different TLS model if the specified
471 model is not supported, or if a better choice of model can be made.
472
473 A variable may be defined as a global ``constant``, which indicates that
474 the contents of the variable will **never** be modified (enabling better
475 optimization, allowing the global data to be placed in the read-only
476 section of an executable, etc). Note that variables that need runtime
477 initialization cannot be marked ``constant`` as there is a store to the
478 variable.
479
480 LLVM explicitly allows *declarations* of global variables to be marked
481 constant, even if the final definition of the global is not. This
482 capability can be used to enable slightly better optimization of the
483 program, but requires the language definition to guarantee that
484 optimizations based on the 'constantness' are valid for the translation
485 units that do not include the definition.
486
487 As SSA values, global variables define pointer values that are in scope
488 (i.e. they dominate) all basic blocks in the program. Global variables
489 always define a pointer to their "content" type because they describe a
490 region of memory, and all memory objects in LLVM are accessed through
491 pointers.
492
493 Global variables can be marked with ``unnamed_addr`` which indicates
494 that the address is not significant, only the content. Constants marked
495 like this can be merged with other constants if they have the same
496 initializer. Note that a constant with significant address *can* be
497 merged with a ``unnamed_addr`` constant, the result being a constant
498 whose address is significant.
499
500 A global variable may be declared to reside in a target-specific
501 numbered address space. For targets that support them, address spaces
502 may affect how optimizations are performed and/or what target
503 instructions are used to access the variable. The default address space
504 is zero. The address space qualifier must precede any other attributes.
505
506 LLVM allows an explicit section to be specified for globals. If the
507 target supports it, it will emit globals to the section specified.
508
509 By default, global initializers are optimized by assuming that global
510 variables defined within the module are not modified from their
511 initial values before the start of the global initializer.  This is
512 true even for variables potentially accessible from outside the
513 module, including those with external linkage or appearing in
514 ``@llvm.used``. This assumption may be suppressed by marking the
515 variable with ``externally_initialized``.
516
517 An explicit alignment may be specified for a global, which must be a
518 power of 2. If not present, or if the alignment is set to zero, the
519 alignment of the global is set by the target to whatever it feels
520 convenient. If an explicit alignment is specified, the global is forced
521 to have exactly that alignment. Targets and optimizers are not allowed
522 to over-align the global if the global has an assigned section. In this
523 case, the extra alignment could be observable: for example, code could
524 assume that the globals are densely packed in their section and try to
525 iterate over them as an array, alignment padding would break this
526 iteration.
527
528 For example, the following defines a global in a numbered address space
529 with an initializer, section, and alignment:
530
531 .. code-block:: llvm
532
533     @G = addrspace(5) constant float 1.0, section "foo", align 4
534
535 The following example defines a thread-local global with the
536 ``initialexec`` TLS model:
537
538 .. code-block:: llvm
539
540     @G = thread_local(initialexec) global i32 0, align 4
541
542 .. _functionstructure:
543
544 Functions
545 ---------
546
547 LLVM function definitions consist of the "``define``" keyword, an
548 optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
549 style <visibility>`, an optional :ref:`calling convention <callingconv>`,
550 an optional ``unnamed_addr`` attribute, a return type, an optional
551 :ref:`parameter attribute <paramattrs>` for the return type, a function
552 name, a (possibly empty) argument list (each with optional :ref:`parameter
553 attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`,
554 an optional section, an optional alignment, an optional :ref:`garbage
555 collector name <gc>`, an optional :ref:`prefix <prefixdata>`, an opening
556 curly brace, a list of basic blocks, and a closing curly brace.
557
558 LLVM function declarations consist of the "``declare``" keyword, an
559 optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
560 style <visibility>`, an optional :ref:`calling convention <callingconv>`,
561 an optional ``unnamed_addr`` attribute, a return type, an optional
562 :ref:`parameter attribute <paramattrs>` for the return type, a function
563 name, a possibly empty list of arguments, an optional alignment, an optional
564 :ref:`garbage collector name <gc>` and an optional :ref:`prefix <prefixdata>`.
565
566 A function definition contains a list of basic blocks, forming the CFG
567 (Control Flow Graph) for the function. Each basic block may optionally
568 start with a label (giving the basic block a symbol table entry),
569 contains a list of instructions, and ends with a
570 :ref:`terminator <terminators>` instruction (such as a branch or function
571 return). If explicit label is not provided, a block is assigned an
572 implicit numbered label, using a next value from the same counter as used
573 for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a
574 function entry block does not have explicit label, it will be assigned
575 label "%0", then first unnamed temporary in that block will be "%1", etc.
576
577 The first basic block in a function is special in two ways: it is
578 immediately executed on entrance to the function, and it is not allowed
579 to have predecessor basic blocks (i.e. there can not be any branches to
580 the entry block of a function). Because the block can have no
581 predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`.
582
583 LLVM allows an explicit section to be specified for functions. If the
584 target supports it, it will emit functions to the section specified.
585
586 An explicit alignment may be specified for a function. If not present,
587 or if the alignment is set to zero, the alignment of the function is set
588 by the target to whatever it feels convenient. If an explicit alignment
589 is specified, the function is forced to have at least that much
590 alignment. All alignments must be a power of 2.
591
592 If the ``unnamed_addr`` attribute is given, the address is know to not
593 be significant and two identical functions can be merged.
594
595 Syntax::
596
597     define [linkage] [visibility]
598            [cconv] [ret attrs]
599            <ResultType> @<FunctionName> ([argument list])
600            [fn Attrs] [section "name"] [align N]
601            [gc] [prefix Constant] { ... }
602
603 .. _langref_aliases:
604
605 Aliases
606 -------
607
608 Aliases act as "second name" for the aliasee value (which can be either
609 function, global variable, another alias or bitcast of global value).
610 Aliases may have an optional :ref:`linkage type <linkage>`, and an optional
611 :ref:`visibility style <visibility>`.
612
613 Syntax::
614
615     @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
616
617 .. _namedmetadatastructure:
618
619 Named Metadata
620 --------------
621
622 Named metadata is a collection of metadata. :ref:`Metadata
623 nodes <metadata>` (but not metadata strings) are the only valid
624 operands for a named metadata.
625
626 Syntax::
627
628     ; Some unnamed metadata nodes, which are referenced by the named metadata.
629     !0 = metadata !{metadata !"zero"}
630     !1 = metadata !{metadata !"one"}
631     !2 = metadata !{metadata !"two"}
632     ; A named metadata.
633     !name = !{!0, !1, !2}
634
635 .. _paramattrs:
636
637 Parameter Attributes
638 --------------------
639
640 The return type and each parameter of a function type may have a set of
641 *parameter attributes* associated with them. Parameter attributes are
642 used to communicate additional information about the result or
643 parameters of a function. Parameter attributes are considered to be part
644 of the function, not of the function type, so functions with different
645 parameter attributes can have the same function type.
646
647 Parameter attributes are simple keywords that follow the type specified.
648 If multiple parameter attributes are needed, they are space separated.
649 For example:
650
651 .. code-block:: llvm
652
653     declare i32 @printf(i8* noalias nocapture, ...)
654     declare i32 @atoi(i8 zeroext)
655     declare signext i8 @returns_signed_char()
656
657 Note that any attributes for the function result (``nounwind``,
658 ``readonly``) come immediately after the argument list.
659
660 Currently, only the following parameter attributes are defined:
661
662 ``zeroext``
663     This indicates to the code generator that the parameter or return
664     value should be zero-extended to the extent required by the target's
665     ABI (which is usually 32-bits, but is 8-bits for a i1 on x86-64) by
666     the caller (for a parameter) or the callee (for a return value).
667 ``signext``
668     This indicates to the code generator that the parameter or return
669     value should be sign-extended to the extent required by the target's
670     ABI (which is usually 32-bits) by the caller (for a parameter) or
671     the callee (for a return value).
672 ``inreg``
673     This indicates that this parameter or return value should be treated
674     in a special target-dependent fashion during while emitting code for
675     a function call or return (usually, by putting it in a register as
676     opposed to memory, though some targets use it to distinguish between
677     two different kinds of registers). Use of this attribute is
678     target-specific.
679 ``byval``
680     This indicates that the pointer parameter should really be passed by
681     value to the function. The attribute implies that a hidden copy of
682     the pointee is made between the caller and the callee, so the callee
683     is unable to modify the value in the caller. This attribute is only
684     valid on LLVM pointer arguments. It is generally used to pass
685     structs and arrays by value, but is also valid on pointers to
686     scalars. The copy is considered to belong to the caller not the
687     callee (for example, ``readonly`` functions should not write to
688     ``byval`` parameters). This is not a valid attribute for return
689     values.
690
691     The byval attribute also supports specifying an alignment with the
692     align attribute. It indicates the alignment of the stack slot to
693     form and the known alignment of the pointer specified to the call
694     site. If the alignment is not specified, then the code generator
695     makes a target-specific assumption.
696
697 ``sret``
698     This indicates that the pointer parameter specifies the address of a
699     structure that is the return value of the function in the source
700     program. This pointer must be guaranteed by the caller to be valid:
701     loads and stores to the structure may be assumed by the callee
702     not to trap and to be properly aligned. This may only be applied to
703     the first parameter. This is not a valid attribute for return
704     values.
705 ``noalias``
706     This indicates that pointer values :ref:`based <pointeraliasing>` on
707     the argument or return value do not alias pointer values which are
708     not *based* on it, ignoring certain "irrelevant" dependencies. For a
709     call to the parent function, dependencies between memory references
710     from before or after the call and from those during the call are
711     "irrelevant" to the ``noalias`` keyword for the arguments and return
712     value used in that call. The caller shares the responsibility with
713     the callee for ensuring that these requirements are met. For further
714     details, please see the discussion of the NoAlias response in `alias
715     analysis <AliasAnalysis.html#MustMayNo>`_.
716
717     Note that this definition of ``noalias`` is intentionally similar
718     to the definition of ``restrict`` in C99 for function arguments,
719     though it is slightly weaker.
720
721     For function return values, C99's ``restrict`` is not meaningful,
722     while LLVM's ``noalias`` is.
723 ``nocapture``
724     This indicates that the callee does not make any copies of the
725     pointer that outlive the callee itself. This is not a valid
726     attribute for return values.
727
728 .. _nest:
729
730 ``nest``
731     This indicates that the pointer parameter can be excised using the
732     :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
733     attribute for return values and can only be applied to one parameter.
734
735 ``returned``
736     This indicates that the function always returns the argument as its return
737     value. This is an optimization hint to the code generator when generating
738     the caller, allowing tail call optimization and omission of register saves
739     and restores in some cases; it is not checked or enforced when generating
740     the callee. The parameter and the function return type must be valid
741     operands for the :ref:`bitcast instruction <i_bitcast>`. This is not a
742     valid attribute for return values and can only be applied to one parameter.
743
744 .. _gc:
745
746 Garbage Collector Names
747 -----------------------
748
749 Each function may specify a garbage collector name, which is simply a
750 string:
751
752 .. code-block:: llvm
753
754     define void @f() gc "name" { ... }
755
756 The compiler declares the supported values of *name*. Specifying a
757 collector which will cause the compiler to alter its output in order to
758 support the named garbage collection algorithm.
759
760 .. _prefixdata:
761
762 Prefix Data
763 -----------
764
765 Prefix data is data associated with a function which the code generator
766 will emit immediately before the function body.  The purpose of this feature
767 is to allow frontends to associate language-specific runtime metadata with
768 specific functions and make it available through the function pointer while
769 still allowing the function pointer to be called.  To access the data for a
770 given function, a program may bitcast the function pointer to a pointer to
771 the constant's type.  This implies that the IR symbol points to the start
772 of the prefix data.
773
774 To maintain the semantics of ordinary function calls, the prefix data must
775 have a particular format.  Specifically, it must begin with a sequence of
776 bytes which decode to a sequence of machine instructions, valid for the
777 module's target, which transfer control to the point immediately succeeding
778 the prefix data, without performing any other visible action.  This allows
779 the inliner and other passes to reason about the semantics of the function
780 definition without needing to reason about the prefix data.  Obviously this
781 makes the format of the prefix data highly target dependent.
782
783 Prefix data is laid out as if it were an initializer for a global variable
784 of the prefix data's type.  No padding is automatically placed between the
785 prefix data and the function body.  If padding is required, it must be part
786 of the prefix data.
787
788 A trivial example of valid prefix data for the x86 architecture is ``i8 144``,
789 which encodes the ``nop`` instruction:
790
791 .. code-block:: llvm
792
793     define void @f() prefix i8 144 { ... }
794
795 Generally prefix data can be formed by encoding a relative branch instruction
796 which skips the metadata, as in this example of valid prefix data for the
797 x86_64 architecture, where the first two bytes encode ``jmp .+10``:
798
799 .. code-block:: llvm
800
801     %0 = type <{ i8, i8, i8* }>
802
803     define void @f() prefix %0 <{ i8 235, i8 8, i8* @md}> { ... }
804
805 A function may have prefix data but no body.  This has similar semantics
806 to the ``available_externally`` linkage in that the data may be used by the
807 optimizers but will not be emitted in the object file.
808
809 .. _attrgrp:
810
811 Attribute Groups
812 ----------------
813
814 Attribute groups are groups of attributes that are referenced by objects within
815 the IR. They are important for keeping ``.ll`` files readable, because a lot of
816 functions will use the same set of attributes. In the degenerative case of a
817 ``.ll`` file that corresponds to a single ``.c`` file, the single attribute
818 group will capture the important command line flags used to build that file.
819
820 An attribute group is a module-level object. To use an attribute group, an
821 object references the attribute group's ID (e.g. ``#37``). An object may refer
822 to more than one attribute group. In that situation, the attributes from the
823 different groups are merged.
824
825 Here is an example of attribute groups for a function that should always be
826 inlined, has a stack alignment of 4, and which shouldn't use SSE instructions:
827
828 .. code-block:: llvm
829
830    ; Target-independent attributes:
831    attributes #0 = { alwaysinline alignstack=4 }
832
833    ; Target-dependent attributes:
834    attributes #1 = { "no-sse" }
835
836    ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".
837    define void @f() #0 #1 { ... }
838
839 .. _fnattrs:
840
841 Function Attributes
842 -------------------
843
844 Function attributes are set to communicate additional information about
845 a function. Function attributes are considered to be part of the
846 function, not of the function type, so functions with different function
847 attributes can have the same function type.
848
849 Function attributes are simple keywords that follow the type specified.
850 If multiple attributes are needed, they are space separated. For
851 example:
852
853 .. code-block:: llvm
854
855     define void @f() noinline { ... }
856     define void @f() alwaysinline { ... }
857     define void @f() alwaysinline optsize { ... }
858     define void @f() optsize { ... }
859
860 ``alignstack(<n>)``
861     This attribute indicates that, when emitting the prologue and
862     epilogue, the backend should forcibly align the stack pointer.
863     Specify the desired alignment, which must be a power of two, in
864     parentheses.
865 ``alwaysinline``
866     This attribute indicates that the inliner should attempt to inline
867     this function into callers whenever possible, ignoring any active
868     inlining size threshold for this caller.
869 ``builtin``
870     This indicates that the callee function at a call site should be
871     recognized as a built-in function, even though the function's declaration
872     uses the ``nobuiltin`` attribute. This is only valid at call sites for
873     direct calls to functions which are declared with the ``nobuiltin``
874     attribute.
875 ``cold``
876     This attribute indicates that this function is rarely called. When
877     computing edge weights, basic blocks post-dominated by a cold
878     function call are also considered to be cold; and, thus, given low
879     weight.
880 ``inlinehint``
881     This attribute indicates that the source code contained a hint that
882     inlining this function is desirable (such as the "inline" keyword in
883     C/C++). It is just a hint; it imposes no requirements on the
884     inliner.
885 ``minsize``
886     This attribute suggests that optimization passes and code generator
887     passes make choices that keep the code size of this function as small
888     as possible and perform optimizations that may sacrifice runtime 
889     performance in order to minimize the size of the generated code.
890 ``naked``
891     This attribute disables prologue / epilogue emission for the
892     function. This can have very system-specific consequences.
893 ``nobuiltin``
894     This indicates that the callee function at a call site is not recognized as
895     a built-in function. LLVM will retain the original call and not replace it
896     with equivalent code based on the semantics of the built-in function, unless
897     the call site uses the ``builtin`` attribute. This is valid at call sites
898     and on function declarations and definitions.
899 ``noduplicate``
900     This attribute indicates that calls to the function cannot be
901     duplicated. A call to a ``noduplicate`` function may be moved
902     within its parent function, but may not be duplicated within
903     its parent function.
904
905     A function containing a ``noduplicate`` call may still
906     be an inlining candidate, provided that the call is not
907     duplicated by inlining. That implies that the function has
908     internal linkage and only has one call site, so the original
909     call is dead after inlining.
910 ``noimplicitfloat``
911     This attributes disables implicit floating point instructions.
912 ``noinline``
913     This attribute indicates that the inliner should never inline this
914     function in any situation. This attribute may not be used together
915     with the ``alwaysinline`` attribute.
916 ``nonlazybind``
917     This attribute suppresses lazy symbol binding for the function. This
918     may make calls to the function faster, at the cost of extra program
919     startup time if the function is not called during program startup.
920 ``noredzone``
921     This attribute indicates that the code generator should not use a
922     red zone, even if the target-specific ABI normally permits it.
923 ``noreturn``
924     This function attribute indicates that the function never returns
925     normally. This produces undefined behavior at runtime if the
926     function ever does dynamically return.
927 ``nounwind``
928     This function attribute indicates that the function never returns
929     with an unwind or exceptional control flow. If the function does
930     unwind, its runtime behavior is undefined.
931 ``optnone``
932     This function attribute indicates that the function is not optimized
933     by any optimization or code generator passes with the 
934     exception of interprocedural optimization passes.
935     This attribute cannot be used together with the ``alwaysinline``
936     attribute; this attribute is also incompatible
937     with the ``minsize`` attribute and the ``optsize`` attribute.
938     
939     The inliner should never inline this function in any situation.
940     Only functions with the ``alwaysinline`` attribute are valid
941     candidates for inlining inside the body of this function.
942 ``optsize``
943     This attribute suggests that optimization passes and code generator
944     passes make choices that keep the code size of this function low,
945     and otherwise do optimizations specifically to reduce code size as
946     long as they do not significantly impact runtime performance.
947 ``readnone``
948     On a function, this attribute indicates that the function computes its
949     result (or decides to unwind an exception) based strictly on its arguments,
950     without dereferencing any pointer arguments or otherwise accessing
951     any mutable state (e.g. memory, control registers, etc) visible to
952     caller functions. It does not write through any pointer arguments
953     (including ``byval`` arguments) and never changes any state visible
954     to callers. This means that it cannot unwind exceptions by calling
955     the ``C++`` exception throwing methods.
956     
957     On an argument, this attribute indicates that the function does not
958     dereference that pointer argument, even though it may read or write the
959     memory that the pointer points to if accessed through other pointers.
960 ``readonly``
961     On a function, this attribute indicates that the function does not write
962     through any pointer arguments (including ``byval`` arguments) or otherwise
963     modify any state (e.g. memory, control registers, etc) visible to
964     caller functions. It may dereference pointer arguments and read
965     state that may be set in the caller. A readonly function always
966     returns the same value (or unwinds an exception identically) when
967     called with the same set of arguments and global state. It cannot
968     unwind an exception by calling the ``C++`` exception throwing
969     methods.
970     
971     On an argument, this attribute indicates that the function does not write
972     through this pointer argument, even though it may write to the memory that
973     the pointer points to.
974 ``returns_twice``
975     This attribute indicates that this function can return twice. The C
976     ``setjmp`` is an example of such a function. The compiler disables
977     some optimizations (like tail calls) in the caller of these
978     functions.
979 ``sanitize_address``
980     This attribute indicates that AddressSanitizer checks
981     (dynamic address safety analysis) are enabled for this function.
982 ``sanitize_memory``
983     This attribute indicates that MemorySanitizer checks (dynamic detection
984     of accesses to uninitialized memory) are enabled for this function.
985 ``sanitize_thread``
986     This attribute indicates that ThreadSanitizer checks
987     (dynamic thread safety analysis) are enabled for this function.
988 ``ssp``
989     This attribute indicates that the function should emit a stack
990     smashing protector. It is in the form of a "canary" --- a random value
991     placed on the stack before the local variables that's checked upon
992     return from the function to see if it has been overwritten. A
993     heuristic is used to determine if a function needs stack protectors
994     or not. The heuristic used will enable protectors for functions with:
995
996     - Character arrays larger than ``ssp-buffer-size`` (default 8).
997     - Aggregates containing character arrays larger than ``ssp-buffer-size``.
998     - Calls to alloca() with variable sizes or constant sizes greater than
999       ``ssp-buffer-size``.
1000
1001     If a function that has an ``ssp`` attribute is inlined into a
1002     function that doesn't have an ``ssp`` attribute, then the resulting
1003     function will have an ``ssp`` attribute.
1004 ``sspreq``
1005     This attribute indicates that the function should *always* emit a
1006     stack smashing protector. This overrides the ``ssp`` function
1007     attribute.
1008
1009     If a function that has an ``sspreq`` attribute is inlined into a
1010     function that doesn't have an ``sspreq`` attribute or which has an
1011     ``ssp`` or ``sspstrong`` attribute, then the resulting function will have
1012     an ``sspreq`` attribute.
1013 ``sspstrong``
1014     This attribute indicates that the function should emit a stack smashing
1015     protector. This attribute causes a strong heuristic to be used when
1016     determining if a function needs stack protectors.  The strong heuristic
1017     will enable protectors for functions with:
1018
1019     - Arrays of any size and type
1020     - Aggregates containing an array of any size and type.
1021     - Calls to alloca().
1022     - Local variables that have had their address taken.
1023
1024     This overrides the ``ssp`` function attribute.
1025
1026     If a function that has an ``sspstrong`` attribute is inlined into a
1027     function that doesn't have an ``sspstrong`` attribute, then the
1028     resulting function will have an ``sspstrong`` attribute.
1029 ``uwtable``
1030     This attribute indicates that the ABI being targeted requires that
1031     an unwind table entry be produce for this function even if we can
1032     show that no exceptions passes by it. This is normally the case for
1033     the ELF x86-64 abi, but it can be disabled for some compilation
1034     units.
1035
1036 .. _moduleasm:
1037
1038 Module-Level Inline Assembly
1039 ----------------------------
1040
1041 Modules may contain "module-level inline asm" blocks, which corresponds
1042 to the GCC "file scope inline asm" blocks. These blocks are internally
1043 concatenated by LLVM and treated as a single unit, but may be separated
1044 in the ``.ll`` file if desired. The syntax is very simple:
1045
1046 .. code-block:: llvm
1047
1048     module asm "inline asm code goes here"
1049     module asm "more can go here"
1050
1051 The strings can contain any character by escaping non-printable
1052 characters. The escape sequence used is simply "\\xx" where "xx" is the
1053 two digit hex code for the number.
1054
1055 The inline asm code is simply printed to the machine code .s file when
1056 assembly code is generated.
1057
1058 .. _langref_datalayout:
1059
1060 Data Layout
1061 -----------
1062
1063 A module may specify a target specific data layout string that specifies
1064 how data is to be laid out in memory. The syntax for the data layout is
1065 simply:
1066
1067 .. code-block:: llvm
1068
1069     target datalayout = "layout specification"
1070
1071 The *layout specification* consists of a list of specifications
1072 separated by the minus sign character ('-'). Each specification starts
1073 with a letter and may include other information after the letter to
1074 define some aspect of the data layout. The specifications accepted are
1075 as follows:
1076
1077 ``E``
1078     Specifies that the target lays out data in big-endian form. That is,
1079     the bits with the most significance have the lowest address
1080     location.
1081 ``e``
1082     Specifies that the target lays out data in little-endian form. That
1083     is, the bits with the least significance have the lowest address
1084     location.
1085 ``S<size>``
1086     Specifies the natural alignment of the stack in bits. Alignment
1087     promotion of stack variables is limited to the natural stack
1088     alignment to avoid dynamic stack realignment. The stack alignment
1089     must be a multiple of 8-bits. If omitted, the natural stack
1090     alignment defaults to "unspecified", which does not prevent any
1091     alignment promotions.
1092 ``p[n]:<size>:<abi>:<pref>``
1093     This specifies the *size* of a pointer and its ``<abi>`` and
1094     ``<pref>``\erred alignments for address space ``n``. All sizes are in
1095     bits. Specifying the ``<pref>`` alignment is optional. If omitted, the
1096     preceding ``:`` should be omitted too. The address space, ``n`` is
1097     optional, and if not specified, denotes the default address space 0.
1098     The value of ``n`` must be in the range [1,2^23).
1099 ``i<size>:<abi>:<pref>``
1100     This specifies the alignment for an integer type of a given bit
1101     ``<size>``. The value of ``<size>`` must be in the range [1,2^23).
1102 ``v<size>:<abi>:<pref>``
1103     This specifies the alignment for a vector type of a given bit
1104     ``<size>``.
1105 ``f<size>:<abi>:<pref>``
1106     This specifies the alignment for a floating point type of a given bit
1107     ``<size>``. Only values of ``<size>`` that are supported by the target
1108     will work. 32 (float) and 64 (double) are supported on all targets; 80
1109     or 128 (different flavors of long double) are also supported on some
1110     targets.
1111 ``a<size>:<abi>:<pref>``
1112     This specifies the alignment for an aggregate type of a given bit
1113     ``<size>``.
1114 ``s<size>:<abi>:<pref>``
1115     This specifies the alignment for a stack object of a given bit
1116     ``<size>``.
1117 ``n<size1>:<size2>:<size3>...``
1118     This specifies a set of native integer widths for the target CPU in
1119     bits. For example, it might contain ``n32`` for 32-bit PowerPC,
1120     ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of
1121     this set are considered to support most general arithmetic operations
1122     efficiently.
1123
1124 When constructing the data layout for a given target, LLVM starts with a
1125 default set of specifications which are then (possibly) overridden by
1126 the specifications in the ``datalayout`` keyword. The default
1127 specifications are given in this list:
1128
1129 -  ``E`` - big endian
1130 -  ``p:64:64:64`` - 64-bit pointers with 64-bit alignment.
1131 -  ``p[n]:64:64:64`` - Other address spaces are assumed to be the
1132    same as the default address space.
1133 -  ``S0`` - natural stack alignment is unspecified
1134 -  ``i1:8:8`` - i1 is 8-bit (byte) aligned
1135 -  ``i8:8:8`` - i8 is 8-bit (byte) aligned
1136 -  ``i16:16:16`` - i16 is 16-bit aligned
1137 -  ``i32:32:32`` - i32 is 32-bit aligned
1138 -  ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
1139    alignment of 64-bits
1140 -  ``f16:16:16`` - half is 16-bit aligned
1141 -  ``f32:32:32`` - float is 32-bit aligned
1142 -  ``f64:64:64`` - double is 64-bit aligned
1143 -  ``f128:128:128`` - quad is 128-bit aligned
1144 -  ``v64:64:64`` - 64-bit vector is 64-bit aligned
1145 -  ``v128:128:128`` - 128-bit vector is 128-bit aligned
1146 -  ``a0:0:64`` - aggregates are 64-bit aligned
1147
1148 When LLVM is determining the alignment for a given type, it uses the
1149 following rules:
1150
1151 #. If the type sought is an exact match for one of the specifications,
1152    that specification is used.
1153 #. If no match is found, and the type sought is an integer type, then
1154    the smallest integer type that is larger than the bitwidth of the
1155    sought type is used. If none of the specifications are larger than
1156    the bitwidth then the largest integer type is used. For example,
1157    given the default specifications above, the i7 type will use the
1158    alignment of i8 (next largest) while both i65 and i256 will use the
1159    alignment of i64 (largest specified).
1160 #. If no match is found, and the type sought is a vector type, then the
1161    largest vector type that is smaller than the sought vector type will
1162    be used as a fall back. This happens because <128 x double> can be
1163    implemented in terms of 64 <2 x double>, for example.
1164
1165 The function of the data layout string may not be what you expect.
1166 Notably, this is not a specification from the frontend of what alignment
1167 the code generator should use.
1168
1169 Instead, if specified, the target data layout is required to match what
1170 the ultimate *code generator* expects. This string is used by the
1171 mid-level optimizers to improve code, and this only works if it matches
1172 what the ultimate code generator uses. If you would like to generate IR
1173 that does not embed this target-specific detail into the IR, then you
1174 don't have to specify the string. This will disable some optimizations
1175 that require precise layout information, but this also prevents those
1176 optimizations from introducing target specificity into the IR.
1177
1178 .. _pointeraliasing:
1179
1180 Pointer Aliasing Rules
1181 ----------------------
1182
1183 Any memory access must be done through a pointer value associated with
1184 an address range of the memory access, otherwise the behavior is
1185 undefined. Pointer values are associated with address ranges according
1186 to the following rules:
1187
1188 -  A pointer value is associated with the addresses associated with any
1189    value it is *based* on.
1190 -  An address of a global variable is associated with the address range
1191    of the variable's storage.
1192 -  The result value of an allocation instruction is associated with the
1193    address range of the allocated storage.
1194 -  A null pointer in the default address-space is associated with no
1195    address.
1196 -  An integer constant other than zero or a pointer value returned from
1197    a function not defined within LLVM may be associated with address
1198    ranges allocated through mechanisms other than those provided by
1199    LLVM. Such ranges shall not overlap with any ranges of addresses
1200    allocated by mechanisms provided by LLVM.
1201
1202 A pointer value is *based* on another pointer value according to the
1203 following rules:
1204
1205 -  A pointer value formed from a ``getelementptr`` operation is *based*
1206    on the first operand of the ``getelementptr``.
1207 -  The result value of a ``bitcast`` is *based* on the operand of the
1208    ``bitcast``.
1209 -  A pointer value formed by an ``inttoptr`` is *based* on all pointer
1210    values that contribute (directly or indirectly) to the computation of
1211    the pointer's value.
1212 -  The "*based* on" relationship is transitive.
1213
1214 Note that this definition of *"based"* is intentionally similar to the
1215 definition of *"based"* in C99, though it is slightly weaker.
1216
1217 LLVM IR does not associate types with memory. The result type of a
1218 ``load`` merely indicates the size and alignment of the memory from
1219 which to load, as well as the interpretation of the value. The first
1220 operand type of a ``store`` similarly only indicates the size and
1221 alignment of the store.
1222
1223 Consequently, type-based alias analysis, aka TBAA, aka
1224 ``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR.
1225 :ref:`Metadata <metadata>` may be used to encode additional information
1226 which specialized optimization passes may use to implement type-based
1227 alias analysis.
1228
1229 .. _volatile:
1230
1231 Volatile Memory Accesses
1232 ------------------------
1233
1234 Certain memory accesses, such as :ref:`load <i_load>`'s,
1235 :ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be
1236 marked ``volatile``. The optimizers must not change the number of
1237 volatile operations or change their order of execution relative to other
1238 volatile operations. The optimizers *may* change the order of volatile
1239 operations relative to non-volatile operations. This is not Java's
1240 "volatile" and has no cross-thread synchronization behavior.
1241
1242 IR-level volatile loads and stores cannot safely be optimized into
1243 llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are
1244 flagged volatile. Likewise, the backend should never split or merge
1245 target-legal volatile load/store instructions.
1246
1247 .. admonition:: Rationale
1248
1249  Platforms may rely on volatile loads and stores of natively supported
1250  data width to be executed as single instruction. For example, in C
1251  this holds for an l-value of volatile primitive type with native
1252  hardware support, but not necessarily for aggregate types. The
1253  frontend upholds these expectations, which are intentionally
1254  unspecified in the IR. The rules above ensure that IR transformation
1255  do not violate the frontend's contract with the language.
1256
1257 .. _memmodel:
1258
1259 Memory Model for Concurrent Operations
1260 --------------------------------------
1261
1262 The LLVM IR does not define any way to start parallel threads of
1263 execution or to register signal handlers. Nonetheless, there are
1264 platform-specific ways to create them, and we define LLVM IR's behavior
1265 in their presence. This model is inspired by the C++0x memory model.
1266
1267 For a more informal introduction to this model, see the :doc:`Atomics`.
1268
1269 We define a *happens-before* partial order as the least partial order
1270 that
1271
1272 -  Is a superset of single-thread program order, and
1273 -  When a *synchronizes-with* ``b``, includes an edge from ``a`` to
1274    ``b``. *Synchronizes-with* pairs are introduced by platform-specific
1275    techniques, like pthread locks, thread creation, thread joining,
1276    etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering
1277    Constraints <ordering>`).
1278
1279 Note that program order does not introduce *happens-before* edges
1280 between a thread and signals executing inside that thread.
1281
1282 Every (defined) read operation (load instructions, memcpy, atomic
1283 loads/read-modify-writes, etc.) R reads a series of bytes written by
1284 (defined) write operations (store instructions, atomic
1285 stores/read-modify-writes, memcpy, etc.). For the purposes of this
1286 section, initialized globals are considered to have a write of the
1287 initializer which is atomic and happens before any other read or write
1288 of the memory in question. For each byte of a read R, R\ :sub:`byte`
1289 may see any write to the same byte, except:
1290
1291 -  If write\ :sub:`1`  happens before write\ :sub:`2`, and
1292    write\ :sub:`2` happens before R\ :sub:`byte`, then
1293    R\ :sub:`byte` does not see write\ :sub:`1`.
1294 -  If R\ :sub:`byte` happens before write\ :sub:`3`, then
1295    R\ :sub:`byte` does not see write\ :sub:`3`.
1296
1297 Given that definition, R\ :sub:`byte` is defined as follows:
1298
1299 -  If R is volatile, the result is target-dependent. (Volatile is
1300    supposed to give guarantees which can support ``sig_atomic_t`` in
1301    C/C++, and may be used for accesses to addresses which do not behave
1302    like normal memory. It does not generally provide cross-thread
1303    synchronization.)
1304 -  Otherwise, if there is no write to the same byte that happens before
1305    R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte.
1306 -  Otherwise, if R\ :sub:`byte` may see exactly one write,
1307    R\ :sub:`byte` returns the value written by that write.
1308 -  Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may
1309    see are atomic, it chooses one of the values written. See the :ref:`Atomic
1310    Memory Ordering Constraints <ordering>` section for additional
1311    constraints on how the choice is made.
1312 -  Otherwise R\ :sub:`byte` returns ``undef``.
1313
1314 R returns the value composed of the series of bytes it read. This
1315 implies that some bytes within the value may be ``undef`` **without**
1316 the entire value being ``undef``. Note that this only defines the
1317 semantics of the operation; it doesn't mean that targets will emit more
1318 than one instruction to read the series of bytes.
1319
1320 Note that in cases where none of the atomic intrinsics are used, this
1321 model places only one restriction on IR transformations on top of what
1322 is required for single-threaded execution: introducing a store to a byte
1323 which might not otherwise be stored is not allowed in general.
1324 (Specifically, in the case where another thread might write to and read
1325 from an address, introducing a store can change a load that may see
1326 exactly one write into a load that may see multiple writes.)
1327
1328 .. _ordering:
1329
1330 Atomic Memory Ordering Constraints
1331 ----------------------------------
1332
1333 Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`,
1334 :ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`,
1335 :ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take
1336 an ordering parameter that determines which other atomic instructions on
1337 the same address they *synchronize with*. These semantics are borrowed
1338 from Java and C++0x, but are somewhat more colloquial. If these
1339 descriptions aren't precise enough, check those specs (see spec
1340 references in the :doc:`atomics guide <Atomics>`).
1341 :ref:`fence <i_fence>` instructions treat these orderings somewhat
1342 differently since they don't take an address. See that instruction's
1343 documentation for details.
1344
1345 For a simpler introduction to the ordering constraints, see the
1346 :doc:`Atomics`.
1347
1348 ``unordered``
1349     The set of values that can be read is governed by the happens-before
1350     partial order. A value cannot be read unless some operation wrote
1351     it. This is intended to provide a guarantee strong enough to model
1352     Java's non-volatile shared variables. This ordering cannot be
1353     specified for read-modify-write operations; it is not strong enough
1354     to make them atomic in any interesting way.
1355 ``monotonic``
1356     In addition to the guarantees of ``unordered``, there is a single
1357     total order for modifications by ``monotonic`` operations on each
1358     address. All modification orders must be compatible with the
1359     happens-before order. There is no guarantee that the modification
1360     orders can be combined to a global total order for the whole program
1361     (and this often will not be possible). The read in an atomic
1362     read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and
1363     :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification
1364     order immediately before the value it writes. If one atomic read
1365     happens before another atomic read of the same address, the later
1366     read must see the same value or a later value in the address's
1367     modification order. This disallows reordering of ``monotonic`` (or
1368     stronger) operations on the same address. If an address is written
1369     ``monotonic``-ally by one thread, and other threads ``monotonic``-ally
1370     read that address repeatedly, the other threads must eventually see
1371     the write. This corresponds to the C++0x/C1x
1372     ``memory_order_relaxed``.
1373 ``acquire``
1374     In addition to the guarantees of ``monotonic``, a
1375     *synchronizes-with* edge may be formed with a ``release`` operation.
1376     This is intended to model C++'s ``memory_order_acquire``.
1377 ``release``
1378     In addition to the guarantees of ``monotonic``, if this operation
1379     writes a value which is subsequently read by an ``acquire``
1380     operation, it *synchronizes-with* that operation. (This isn't a
1381     complete description; see the C++0x definition of a release
1382     sequence.) This corresponds to the C++0x/C1x
1383     ``memory_order_release``.
1384 ``acq_rel`` (acquire+release)
1385     Acts as both an ``acquire`` and ``release`` operation on its
1386     address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``.
1387 ``seq_cst`` (sequentially consistent)
1388     In addition to the guarantees of ``acq_rel`` (``acquire`` for an
1389     operation which only reads, ``release`` for an operation which only
1390     writes), there is a global total order on all
1391     sequentially-consistent operations on all addresses, which is
1392     consistent with the *happens-before* partial order and with the
1393     modification orders of all the affected addresses. Each
1394     sequentially-consistent read sees the last preceding write to the
1395     same address in this global order. This corresponds to the C++0x/C1x
1396     ``memory_order_seq_cst`` and Java volatile.
1397
1398 .. _singlethread:
1399
1400 If an atomic operation is marked ``singlethread``, it only *synchronizes
1401 with* or participates in modification and seq\_cst total orderings with
1402 other operations running in the same thread (for example, in signal
1403 handlers).
1404
1405 .. _fastmath:
1406
1407 Fast-Math Flags
1408 ---------------
1409
1410 LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`,
1411 :ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
1412 :ref:`frem <i_frem>`) have the following flags that can set to enable
1413 otherwise unsafe floating point operations
1414
1415 ``nnan``
1416    No NaNs - Allow optimizations to assume the arguments and result are not
1417    NaN. Such optimizations are required to retain defined behavior over
1418    NaNs, but the value of the result is undefined.
1419
1420 ``ninf``
1421    No Infs - Allow optimizations to assume the arguments and result are not
1422    +/-Inf. Such optimizations are required to retain defined behavior over
1423    +/-Inf, but the value of the result is undefined.
1424
1425 ``nsz``
1426    No Signed Zeros - Allow optimizations to treat the sign of a zero
1427    argument or result as insignificant.
1428
1429 ``arcp``
1430    Allow Reciprocal - Allow optimizations to use the reciprocal of an
1431    argument rather than perform division.
1432
1433 ``fast``
1434    Fast - Allow algebraically equivalent transformations that may
1435    dramatically change results in floating point (e.g. reassociate). This
1436    flag implies all the others.
1437
1438 .. _typesystem:
1439
1440 Type System
1441 ===========
1442
1443 The LLVM type system is one of the most important features of the
1444 intermediate representation. Being typed enables a number of
1445 optimizations to be performed on the intermediate representation
1446 directly, without having to do extra analyses on the side before the
1447 transformation. A strong type system makes it easier to read the
1448 generated code and enables novel analyses and transformations that are
1449 not feasible to perform on normal three address code representations.
1450
1451 .. _typeclassifications:
1452
1453 Type Classifications
1454 --------------------
1455
1456 The types fall into a few useful classifications:
1457
1458
1459 .. list-table::
1460    :header-rows: 1
1461
1462    * - Classification
1463      - Types
1464
1465    * - :ref:`integer <t_integer>`
1466      - ``i1``, ``i2``, ``i3``, ... ``i8``, ... ``i16``, ... ``i32``, ...
1467        ``i64``, ...
1468
1469    * - :ref:`floating point <t_floating>`
1470      - ``half``, ``float``, ``double``, ``x86_fp80``, ``fp128``,
1471        ``ppc_fp128``
1472
1473
1474    * - first class
1475
1476        .. _t_firstclass:
1477
1478      - :ref:`integer <t_integer>`, :ref:`floating point <t_floating>`,
1479        :ref:`pointer <t_pointer>`, :ref:`vector <t_vector>`,
1480        :ref:`structure <t_struct>`, :ref:`array <t_array>`,
1481        :ref:`label <t_label>`, :ref:`metadata <t_metadata>`.
1482
1483    * - :ref:`primitive <t_primitive>`
1484      - :ref:`label <t_label>`,
1485        :ref:`void <t_void>`,
1486        :ref:`integer <t_integer>`,
1487        :ref:`floating point <t_floating>`,
1488        :ref:`x86mmx <t_x86mmx>`,
1489        :ref:`metadata <t_metadata>`.
1490
1491    * - :ref:`derived <t_derived>`
1492      - :ref:`array <t_array>`,
1493        :ref:`function <t_function>`,
1494        :ref:`pointer <t_pointer>`,
1495        :ref:`structure <t_struct>`,
1496        :ref:`vector <t_vector>`,
1497        :ref:`opaque <t_opaque>`.
1498
1499 The :ref:`first class <t_firstclass>` types are perhaps the most important.
1500 Values of these types are the only ones which can be produced by
1501 instructions.
1502
1503 .. _t_primitive:
1504
1505 Primitive Types
1506 ---------------
1507
1508 The primitive types are the fundamental building blocks of the LLVM
1509 system.
1510
1511 .. _t_integer:
1512
1513 Integer Type
1514 ^^^^^^^^^^^^
1515
1516 Overview:
1517 """""""""
1518
1519 The integer type is a very simple type that simply specifies an
1520 arbitrary bit width for the integer type desired. Any bit width from 1
1521 bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified.
1522
1523 Syntax:
1524 """""""
1525
1526 ::
1527
1528       iN
1529
1530 The number of bits the integer will occupy is specified by the ``N``
1531 value.
1532
1533 Examples:
1534 """""""""
1535
1536 +----------------+------------------------------------------------+
1537 | ``i1``         | a single-bit integer.                          |
1538 +----------------+------------------------------------------------+
1539 | ``i32``        | a 32-bit integer.                              |
1540 +----------------+------------------------------------------------+
1541 | ``i1942652``   | a really big integer of over 1 million bits.   |
1542 +----------------+------------------------------------------------+
1543
1544 .. _t_floating:
1545
1546 Floating Point Types
1547 ^^^^^^^^^^^^^^^^^^^^
1548
1549 .. list-table::
1550    :header-rows: 1
1551
1552    * - Type
1553      - Description
1554
1555    * - ``half``
1556      - 16-bit floating point value
1557
1558    * - ``float``
1559      - 32-bit floating point value
1560
1561    * - ``double``
1562      - 64-bit floating point value
1563
1564    * - ``fp128``
1565      - 128-bit floating point value (112-bit mantissa)
1566
1567    * - ``x86_fp80``
1568      -  80-bit floating point value (X87)
1569
1570    * - ``ppc_fp128``
1571      - 128-bit floating point value (two 64-bits)
1572
1573 .. _t_x86mmx:
1574
1575 X86mmx Type
1576 ^^^^^^^^^^^
1577
1578 Overview:
1579 """""""""
1580
1581 The x86mmx type represents a value held in an MMX register on an x86
1582 machine. The operations allowed on it are quite limited: parameters and
1583 return values, load and store, and bitcast. User-specified MMX
1584 instructions are represented as intrinsic or asm calls with arguments
1585 and/or results of this type. There are no arrays, vectors or constants
1586 of this type.
1587
1588 Syntax:
1589 """""""
1590
1591 ::
1592
1593       x86mmx
1594
1595 .. _t_void:
1596
1597 Void Type
1598 ^^^^^^^^^
1599
1600 Overview:
1601 """""""""
1602
1603 The void type does not represent any value and has no size.
1604
1605 Syntax:
1606 """""""
1607
1608 ::
1609
1610       void
1611
1612 .. _t_label:
1613
1614 Label Type
1615 ^^^^^^^^^^
1616
1617 Overview:
1618 """""""""
1619
1620 The label type represents code labels.
1621
1622 Syntax:
1623 """""""
1624
1625 ::
1626
1627       label
1628
1629 .. _t_metadata:
1630
1631 Metadata Type
1632 ^^^^^^^^^^^^^
1633
1634 Overview:
1635 """""""""
1636
1637 The metadata type represents embedded metadata. No derived types may be
1638 created from metadata except for :ref:`function <t_function>` arguments.
1639
1640 Syntax:
1641 """""""
1642
1643 ::
1644
1645       metadata
1646
1647 .. _t_derived:
1648
1649 Derived Types
1650 -------------
1651
1652 The real power in LLVM comes from the derived types in the system. This
1653 is what allows a programmer to represent arrays, functions, pointers,
1654 and other useful types. Each of these types contain one or more element
1655 types which may be a primitive type, or another derived type. For
1656 example, it is possible to have a two dimensional array, using an array
1657 as the element type of another array.
1658
1659 .. _t_aggregate:
1660
1661 Aggregate Types
1662 ^^^^^^^^^^^^^^^
1663
1664 Aggregate Types are a subset of derived types that can contain multiple
1665 member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are
1666 aggregate types. :ref:`Vectors <t_vector>` are not considered to be
1667 aggregate types.
1668
1669 .. _t_array:
1670
1671 Array Type
1672 ^^^^^^^^^^
1673
1674 Overview:
1675 """""""""
1676
1677 The array type is a very simple derived type that arranges elements
1678 sequentially in memory. The array type requires a size (number of
1679 elements) and an underlying data type.
1680
1681 Syntax:
1682 """""""
1683
1684 ::
1685
1686       [<# elements> x <elementtype>]
1687
1688 The number of elements is a constant integer value; ``elementtype`` may
1689 be any type with a size.
1690
1691 Examples:
1692 """""""""
1693
1694 +------------------+--------------------------------------+
1695 | ``[40 x i32]``   | Array of 40 32-bit integer values.   |
1696 +------------------+--------------------------------------+
1697 | ``[41 x i32]``   | Array of 41 32-bit integer values.   |
1698 +------------------+--------------------------------------+
1699 | ``[4 x i8]``     | Array of 4 8-bit integer values.     |
1700 +------------------+--------------------------------------+
1701
1702 Here are some examples of multidimensional arrays:
1703
1704 +-----------------------------+----------------------------------------------------------+
1705 | ``[3 x [4 x i32]]``         | 3x4 array of 32-bit integer values.                      |
1706 +-----------------------------+----------------------------------------------------------+
1707 | ``[12 x [10 x float]]``     | 12x10 array of single precision floating point values.   |
1708 +-----------------------------+----------------------------------------------------------+
1709 | ``[2 x [3 x [4 x i16]]]``   | 2x3x4 array of 16-bit integer values.                    |
1710 +-----------------------------+----------------------------------------------------------+
1711
1712 There is no restriction on indexing beyond the end of the array implied
1713 by a static type (though there are restrictions on indexing beyond the
1714 bounds of an allocated object in some cases). This means that
1715 single-dimension 'variable sized array' addressing can be implemented in
1716 LLVM with a zero length array type. An implementation of 'pascal style
1717 arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for
1718 example.
1719
1720 .. _t_function:
1721
1722 Function Type
1723 ^^^^^^^^^^^^^
1724
1725 Overview:
1726 """""""""
1727
1728 The function type can be thought of as a function signature. It consists
1729 of a return type and a list of formal parameter types. The return type
1730 of a function type is a first class type or a void type.
1731
1732 Syntax:
1733 """""""
1734
1735 ::
1736
1737       <returntype> (<parameter list>)
1738
1739 ...where '``<parameter list>``' is a comma-separated list of type
1740 specifiers. Optionally, the parameter list may include a type ``...``,
1741 which indicates that the function takes a variable number of arguments.
1742 Variable argument functions can access their arguments with the
1743 :ref:`variable argument handling intrinsic <int_varargs>` functions.
1744 '``<returntype>``' is any type except :ref:`label <t_label>`.
1745
1746 Examples:
1747 """""""""
1748
1749 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1750 | ``i32 (i32)``                   | function taking an ``i32``, returning an ``i32``                                                                                                                    |
1751 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1752 | ``float (i16, i32 *) *``        | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``.                                    |
1753 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1754 | ``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. |
1755 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1756 | ``{i32, i32} (i32)``            | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values                                                                 |
1757 +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1758
1759 .. _t_struct:
1760
1761 Structure Type
1762 ^^^^^^^^^^^^^^
1763
1764 Overview:
1765 """""""""
1766
1767 The structure type is used to represent a collection of data members
1768 together in memory. The elements of a structure may be any type that has
1769 a size.
1770
1771 Structures in memory are accessed using '``load``' and '``store``' by
1772 getting a pointer to a field with the '``getelementptr``' instruction.
1773 Structures in registers are accessed using the '``extractvalue``' and
1774 '``insertvalue``' instructions.
1775
1776 Structures may optionally be "packed" structures, which indicate that
1777 the alignment of the struct is one byte, and that there is no padding
1778 between the elements. In non-packed structs, padding between field types
1779 is inserted as defined by the DataLayout string in the module, which is
1780 required to match what the underlying code generator expects.
1781
1782 Structures can either be "literal" or "identified". A literal structure
1783 is defined inline with other types (e.g. ``{i32, i32}*``) whereas
1784 identified types are always defined at the top level with a name.
1785 Literal types are uniqued by their contents and can never be recursive
1786 or opaque since there is no way to write one. Identified types can be
1787 recursive, can be opaqued, and are never uniqued.
1788
1789 Syntax:
1790 """""""
1791
1792 ::
1793
1794       %T1 = type { <type list> }     ; Identified normal struct type
1795       %T2 = type <{ <type list> }>   ; Identified packed struct type
1796
1797 Examples:
1798 """""""""
1799
1800 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1801 | ``{ i32, i32, i32 }``        | A triple of three ``i32`` values                                                                                                                                                      |
1802 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1803 | ``{ 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``.  |
1804 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1805 | ``<{ i8, i32 }>``            | A packed struct known to be 5 bytes in size.                                                                                                                                          |
1806 +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1807
1808 .. _t_opaque:
1809
1810 Opaque Structure Types
1811 ^^^^^^^^^^^^^^^^^^^^^^
1812
1813 Overview:
1814 """""""""
1815
1816 Opaque structure types are used to represent named structure types that
1817 do not have a body specified. This corresponds (for example) to the C
1818 notion of a forward declared structure.
1819
1820 Syntax:
1821 """""""
1822
1823 ::
1824
1825       %X = type opaque
1826       %52 = type opaque
1827
1828 Examples:
1829 """""""""
1830
1831 +--------------+-------------------+
1832 | ``opaque``   | An opaque type.   |
1833 +--------------+-------------------+
1834
1835 .. _t_pointer:
1836
1837 Pointer Type
1838 ^^^^^^^^^^^^
1839
1840 Overview:
1841 """""""""
1842
1843 The pointer type is used to specify memory locations. Pointers are
1844 commonly used to reference objects in memory.
1845
1846 Pointer types may have an optional address space attribute defining the
1847 numbered address space where the pointed-to object resides. The default
1848 address space is number zero. The semantics of non-zero address spaces
1849 are target-specific.
1850
1851 Note that LLVM does not permit pointers to void (``void*``) nor does it
1852 permit pointers to labels (``label*``). Use ``i8*`` instead.
1853
1854 Syntax:
1855 """""""
1856
1857 ::
1858
1859       <type> *
1860
1861 Examples:
1862 """""""""
1863
1864 +-------------------------+--------------------------------------------------------------------------------------------------------------+
1865 | ``[4 x i32]*``          | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values.                               |
1866 +-------------------------+--------------------------------------------------------------------------------------------------------------+
1867 | ``i32 (i32*) *``        | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. |
1868 +-------------------------+--------------------------------------------------------------------------------------------------------------+
1869 | ``i32 addrspace(5)*``   | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5.                           |
1870 +-------------------------+--------------------------------------------------------------------------------------------------------------+
1871
1872 .. _t_vector:
1873
1874 Vector Type
1875 ^^^^^^^^^^^
1876
1877 Overview:
1878 """""""""
1879
1880 A vector type is a simple derived type that represents a vector of
1881 elements. Vector types are used when multiple primitive data are
1882 operated in parallel using a single instruction (SIMD). A vector type
1883 requires a size (number of elements) and an underlying primitive data
1884 type. Vector types are considered :ref:`first class <t_firstclass>`.
1885
1886 Syntax:
1887 """""""
1888
1889 ::
1890
1891       < <# elements> x <elementtype> >
1892
1893 The number of elements is a constant integer value larger than 0;
1894 elementtype may be any integer or floating point type, or a pointer to
1895 these types. Vectors of size zero are not allowed.
1896
1897 Examples:
1898 """""""""
1899
1900 +-------------------+--------------------------------------------------+
1901 | ``<4 x i32>``     | Vector of 4 32-bit integer values.               |
1902 +-------------------+--------------------------------------------------+
1903 | ``<8 x float>``   | Vector of 8 32-bit floating-point values.        |
1904 +-------------------+--------------------------------------------------+
1905 | ``<2 x i64>``     | Vector of 2 64-bit integer values.               |
1906 +-------------------+--------------------------------------------------+
1907 | ``<4 x i64*>``    | Vector of 4 pointers to 64-bit integer values.   |
1908 +-------------------+--------------------------------------------------+
1909
1910 Constants
1911 =========
1912
1913 LLVM has several different basic types of constants. This section
1914 describes them all and their syntax.
1915
1916 Simple Constants
1917 ----------------
1918
1919 **Boolean constants**
1920     The two strings '``true``' and '``false``' are both valid constants
1921     of the ``i1`` type.
1922 **Integer constants**
1923     Standard integers (such as '4') are constants of the
1924     :ref:`integer <t_integer>` type. Negative numbers may be used with
1925     integer types.
1926 **Floating point constants**
1927     Floating point constants use standard decimal notation (e.g.
1928     123.421), exponential notation (e.g. 1.23421e+2), or a more precise
1929     hexadecimal notation (see below). The assembler requires the exact
1930     decimal value of a floating-point constant. For example, the
1931     assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating
1932     decimal in binary. Floating point constants must have a :ref:`floating
1933     point <t_floating>` type.
1934 **Null pointer constants**
1935     The identifier '``null``' is recognized as a null pointer constant
1936     and must be of :ref:`pointer type <t_pointer>`.
1937
1938 The one non-intuitive notation for constants is the hexadecimal form of
1939 floating point constants. For example, the form
1940 '``double    0x432ff973cafa8000``' is equivalent to (but harder to read
1941 than) '``double 4.5e+15``'. The only time hexadecimal floating point
1942 constants are required (and the only time that they are generated by the
1943 disassembler) is when a floating point constant must be emitted but it
1944 cannot be represented as a decimal floating point number in a reasonable
1945 number of digits. For example, NaN's, infinities, and other special
1946 values are represented in their IEEE hexadecimal format so that assembly
1947 and disassembly do not cause any bits to change in the constants.
1948
1949 When using the hexadecimal form, constants of types half, float, and
1950 double are represented using the 16-digit form shown above (which
1951 matches the IEEE754 representation for double); half and float values
1952 must, however, be exactly representable as IEEE 754 half and single
1953 precision, respectively. Hexadecimal format is always used for long
1954 double, and there are three forms of long double. The 80-bit format used
1955 by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The
1956 128-bit format used by PowerPC (two adjacent doubles) is represented by
1957 ``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is
1958 represented by ``0xL`` followed by 32 hexadecimal digits. Long doubles
1959 will only work if they match the long double format on your target.
1960 The IEEE 16-bit format (half precision) is represented by ``0xH``
1961 followed by 4 hexadecimal digits. All hexadecimal formats are big-endian
1962 (sign bit at the left).
1963
1964 There are no constants of type x86mmx.
1965
1966 .. _complexconstants:
1967
1968 Complex Constants
1969 -----------------
1970
1971 Complex constants are a (potentially recursive) combination of simple
1972 constants and smaller complex constants.
1973
1974 **Structure constants**
1975     Structure constants are represented with notation similar to
1976     structure type definitions (a comma separated list of elements,
1977     surrounded by braces (``{}``)). For example:
1978     "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as
1979     "``@G = external global i32``". Structure constants must have
1980     :ref:`structure type <t_struct>`, and the number and types of elements
1981     must match those specified by the type.
1982 **Array constants**
1983     Array constants are represented with notation similar to array type
1984     definitions (a comma separated list of elements, surrounded by
1985     square brackets (``[]``)). For example:
1986     "``[ i32 42, i32 11, i32 74 ]``". Array constants must have
1987     :ref:`array type <t_array>`, and the number and types of elements must
1988     match those specified by the type.
1989 **Vector constants**
1990     Vector constants are represented with notation similar to vector
1991     type definitions (a comma separated list of elements, surrounded by
1992     less-than/greater-than's (``<>``)). For example:
1993     "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants
1994     must have :ref:`vector type <t_vector>`, and the number and types of
1995     elements must match those specified by the type.
1996 **Zero initialization**
1997     The string '``zeroinitializer``' can be used to zero initialize a
1998     value to zero of *any* type, including scalar and
1999     :ref:`aggregate <t_aggregate>` types. This is often used to avoid
2000     having to print large zero initializers (e.g. for large arrays) and
2001     is always exactly equivalent to using explicit zero initializers.
2002 **Metadata node**
2003     A metadata node is a structure-like constant with :ref:`metadata
2004     type <t_metadata>`. For example:
2005     "``metadata !{ i32 0, metadata !"test" }``". Unlike other
2006     constants that are meant to be interpreted as part of the
2007     instruction stream, metadata is a place to attach additional
2008     information such as debug info.
2009
2010 Global Variable and Function Addresses
2011 --------------------------------------
2012
2013 The addresses of :ref:`global variables <globalvars>` and
2014 :ref:`functions <functionstructure>` are always implicitly valid
2015 (link-time) constants. These constants are explicitly referenced when
2016 the :ref:`identifier for the global <identifiers>` is used and always have
2017 :ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM
2018 file:
2019
2020 .. code-block:: llvm
2021
2022     @X = global i32 17
2023     @Y = global i32 42
2024     @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
2025
2026 .. _undefvalues:
2027
2028 Undefined Values
2029 ----------------
2030
2031 The string '``undef``' can be used anywhere a constant is expected, and
2032 indicates that the user of the value may receive an unspecified
2033 bit-pattern. Undefined values may be of any type (other than '``label``'
2034 or '``void``') and be used anywhere a constant is permitted.
2035
2036 Undefined values are useful because they indicate to the compiler that
2037 the program is well defined no matter what value is used. This gives the
2038 compiler more freedom to optimize. Here are some examples of
2039 (potentially surprising) transformations that are valid (in pseudo IR):
2040
2041 .. code-block:: llvm
2042
2043       %A = add %X, undef
2044       %B = sub %X, undef
2045       %C = xor %X, undef
2046     Safe:
2047       %A = undef
2048       %B = undef
2049       %C = undef
2050
2051 This is safe because all of the output bits are affected by the undef
2052 bits. Any output bit can have a zero or one depending on the input bits.
2053
2054 .. code-block:: llvm
2055
2056       %A = or %X, undef
2057       %B = and %X, undef
2058     Safe:
2059       %A = -1
2060       %B = 0
2061     Unsafe:
2062       %A = undef
2063       %B = undef
2064
2065 These logical operations have bits that are not always affected by the
2066 input. For example, if ``%X`` has a zero bit, then the output of the
2067 '``and``' operation will always be a zero for that bit, no matter what
2068 the corresponding bit from the '``undef``' is. As such, it is unsafe to
2069 optimize or assume that the result of the '``and``' is '``undef``'.
2070 However, it is safe to assume that all bits of the '``undef``' could be
2071 0, and optimize the '``and``' to 0. Likewise, it is safe to assume that
2072 all the bits of the '``undef``' operand to the '``or``' could be set,
2073 allowing the '``or``' to be folded to -1.
2074
2075 .. code-block:: llvm
2076
2077       %A = select undef, %X, %Y
2078       %B = select undef, 42, %Y
2079       %C = select %X, %Y, undef
2080     Safe:
2081       %A = %X     (or %Y)
2082       %B = 42     (or %Y)
2083       %C = %Y
2084     Unsafe:
2085       %A = undef
2086       %B = undef
2087       %C = undef
2088
2089 This set of examples shows that undefined '``select``' (and conditional
2090 branch) conditions can go *either way*, but they have to come from one
2091 of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were
2092 both known to have a clear low bit, then ``%A`` would have to have a
2093 cleared low bit. However, in the ``%C`` example, the optimizer is
2094 allowed to assume that the '``undef``' operand could be the same as
2095 ``%Y``, allowing the whole '``select``' to be eliminated.
2096
2097 .. code-block:: llvm
2098
2099       %A = xor undef, undef
2100
2101       %B = undef
2102       %C = xor %B, %B
2103
2104       %D = undef
2105       %E = icmp lt %D, 4
2106       %F = icmp gte %D, 4
2107
2108     Safe:
2109       %A = undef
2110       %B = undef
2111       %C = undef
2112       %D = undef
2113       %E = undef
2114       %F = undef
2115
2116 This example points out that two '``undef``' operands are not
2117 necessarily the same. This can be surprising to people (and also matches
2118 C semantics) where they assume that "``X^X``" is always zero, even if
2119 ``X`` is undefined. This isn't true for a number of reasons, but the
2120 short answer is that an '``undef``' "variable" can arbitrarily change
2121 its value over its "live range". This is true because the variable
2122 doesn't actually *have a live range*. Instead, the value is logically
2123 read from arbitrary registers that happen to be around when needed, so
2124 the value is not necessarily consistent over time. In fact, ``%A`` and
2125 ``%C`` need to have the same semantics or the core LLVM "replace all
2126 uses with" concept would not hold.
2127
2128 .. code-block:: llvm
2129
2130       %A = fdiv undef, %X
2131       %B = fdiv %X, undef
2132     Safe:
2133       %A = undef
2134     b: unreachable
2135
2136 These examples show the crucial difference between an *undefined value*
2137 and *undefined behavior*. An undefined value (like '``undef``') is
2138 allowed to have an arbitrary bit-pattern. This means that the ``%A``
2139 operation can be constant folded to '``undef``', because the '``undef``'
2140 could be an SNaN, and ``fdiv`` is not (currently) defined on SNaN's.
2141 However, in the second example, we can make a more aggressive
2142 assumption: because the ``undef`` is allowed to be an arbitrary value,
2143 we are allowed to assume that it could be zero. Since a divide by zero
2144 has *undefined behavior*, we are allowed to assume that the operation
2145 does not execute at all. This allows us to delete the divide and all
2146 code after it. Because the undefined operation "can't happen", the
2147 optimizer can assume that it occurs in dead code.
2148
2149 .. code-block:: llvm
2150
2151     a:  store undef -> %X
2152     b:  store %X -> undef
2153     Safe:
2154     a: <deleted>
2155     b: unreachable
2156
2157 These examples reiterate the ``fdiv`` example: a store *of* an undefined
2158 value can be assumed to not have any effect; we can assume that the
2159 value is overwritten with bits that happen to match what was already
2160 there. However, a store *to* an undefined location could clobber
2161 arbitrary memory, therefore, it has undefined behavior.
2162
2163 .. _poisonvalues:
2164
2165 Poison Values
2166 -------------
2167
2168 Poison values are similar to :ref:`undef values <undefvalues>`, however
2169 they also represent the fact that an instruction or constant expression
2170 which cannot evoke side effects has nevertheless detected a condition
2171 which results in undefined behavior.
2172
2173 There is currently no way of representing a poison value in the IR; they
2174 only exist when produced by operations such as :ref:`add <i_add>` with
2175 the ``nsw`` flag.
2176
2177 Poison value behavior is defined in terms of value *dependence*:
2178
2179 -  Values other than :ref:`phi <i_phi>` nodes depend on their operands.
2180 -  :ref:`Phi <i_phi>` nodes depend on the operand corresponding to
2181    their dynamic predecessor basic block.
2182 -  Function arguments depend on the corresponding actual argument values
2183    in the dynamic callers of their functions.
2184 -  :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>`
2185    instructions that dynamically transfer control back to them.
2186 -  :ref:`Invoke <i_invoke>` instructions depend on the
2187    :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing
2188    call instructions that dynamically transfer control back to them.
2189 -  Non-volatile loads and stores depend on the most recent stores to all
2190    of the referenced memory addresses, following the order in the IR
2191    (including loads and stores implied by intrinsics such as
2192    :ref:`@llvm.memcpy <int_memcpy>`.)
2193 -  An instruction with externally visible side effects depends on the
2194    most recent preceding instruction with externally visible side
2195    effects, following the order in the IR. (This includes :ref:`volatile
2196    operations <volatile>`.)
2197 -  An instruction *control-depends* on a :ref:`terminator
2198    instruction <terminators>` if the terminator instruction has
2199    multiple successors and the instruction is always executed when
2200    control transfers to one of the successors, and may not be executed
2201    when control is transferred to another.
2202 -  Additionally, an instruction also *control-depends* on a terminator
2203    instruction if the set of instructions it otherwise depends on would
2204    be different if the terminator had transferred control to a different
2205    successor.
2206 -  Dependence is transitive.
2207
2208 Poison Values have the same behavior as :ref:`undef values <undefvalues>`,
2209 with the additional affect that any instruction which has a *dependence*
2210 on a poison value has undefined behavior.
2211
2212 Here are some examples:
2213
2214 .. code-block:: llvm
2215
2216     entry:
2217       %poison = sub nuw i32 0, 1           ; Results in a poison value.
2218       %still_poison = and i32 %poison, 0   ; 0, but also poison.
2219       %poison_yet_again = getelementptr i32* @h, i32 %still_poison
2220       store i32 0, i32* %poison_yet_again  ; memory at @h[0] is poisoned
2221
2222       store i32 %poison, i32* @g           ; Poison value stored to memory.
2223       %poison2 = load i32* @g              ; Poison value loaded back from memory.
2224
2225       store volatile i32 %poison, i32* @g  ; External observation; undefined behavior.
2226
2227       %narrowaddr = bitcast i32* @g to i16*
2228       %wideaddr = bitcast i32* @g to i64*
2229       %poison3 = load i16* %narrowaddr     ; Returns a poison value.
2230       %poison4 = load i64* %wideaddr       ; Returns a poison value.
2231
2232       %cmp = icmp slt i32 %poison, 0       ; Returns a poison value.
2233       br i1 %cmp, label %true, label %end  ; Branch to either destination.
2234
2235     true:
2236       store volatile i32 0, i32* @g        ; This is control-dependent on %cmp, so
2237                                            ; it has undefined behavior.
2238       br label %end
2239
2240     end:
2241       %p = phi i32 [ 0, %entry ], [ 1, %true ]
2242                                            ; Both edges into this PHI are
2243                                            ; control-dependent on %cmp, so this
2244                                            ; always results in a poison value.
2245
2246       store volatile i32 0, i32* @g        ; This would depend on the store in %true
2247                                            ; if %cmp is true, or the store in %entry
2248                                            ; otherwise, so this is undefined behavior.
2249
2250       br i1 %cmp, label %second_true, label %second_end
2251                                            ; The same branch again, but this time the
2252                                            ; true block doesn't have side effects.
2253
2254     second_true:
2255       ; No side effects!
2256       ret void
2257
2258     second_end:
2259       store volatile i32 0, i32* @g        ; This time, the instruction always depends
2260                                            ; on the store in %end. Also, it is
2261                                            ; control-equivalent to %end, so this is
2262                                            ; well-defined (ignoring earlier undefined
2263                                            ; behavior in this example).
2264
2265 .. _blockaddress:
2266
2267 Addresses of Basic Blocks
2268 -------------------------
2269
2270 ``blockaddress(@function, %block)``
2271
2272 The '``blockaddress``' constant computes the address of the specified
2273 basic block in the specified function, and always has an ``i8*`` type.
2274 Taking the address of the entry block is illegal.
2275
2276 This value only has defined behavior when used as an operand to the
2277 ':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons
2278 against null. Pointer equality tests between labels addresses results in
2279 undefined behavior --- though, again, comparison against null is ok, and
2280 no label is equal to the null pointer. This may be passed around as an
2281 opaque pointer sized value as long as the bits are not inspected. This
2282 allows ``ptrtoint`` and arithmetic to be performed on these values so
2283 long as the original value is reconstituted before the ``indirectbr``
2284 instruction.
2285
2286 Finally, some targets may provide defined semantics when using the value
2287 as the operand to an inline assembly, but that is target specific.
2288
2289 .. _constantexprs:
2290
2291 Constant Expressions
2292 --------------------
2293
2294 Constant expressions are used to allow expressions involving other
2295 constants to be used as constants. Constant expressions may be of any
2296 :ref:`first class <t_firstclass>` type and may involve any LLVM operation
2297 that does not have side effects (e.g. load and call are not supported).
2298 The following is the syntax for constant expressions:
2299
2300 ``trunc (CST to TYPE)``
2301     Truncate a constant to another type. The bit size of CST must be
2302     larger than the bit size of TYPE. Both types must be integers.
2303 ``zext (CST to TYPE)``
2304     Zero extend a constant to another type. The bit size of CST must be
2305     smaller than the bit size of TYPE. Both types must be integers.
2306 ``sext (CST to TYPE)``
2307     Sign extend a constant to another type. The bit size of CST must be
2308     smaller than the bit size of TYPE. Both types must be integers.
2309 ``fptrunc (CST to TYPE)``
2310     Truncate a floating point constant to another floating point type.
2311     The size of CST must be larger than the size of TYPE. Both types
2312     must be floating point.
2313 ``fpext (CST to TYPE)``
2314     Floating point extend a constant to another type. The size of CST
2315     must be smaller or equal to the size of TYPE. Both types must be
2316     floating point.
2317 ``fptoui (CST to TYPE)``
2318     Convert a floating point constant to the corresponding unsigned
2319     integer constant. TYPE must be a scalar or vector integer type. CST
2320     must be of scalar or vector floating point type. Both CST and TYPE
2321     must be scalars, or vectors of the same number of elements. If the
2322     value won't fit in the integer type, the results are undefined.
2323 ``fptosi (CST to TYPE)``
2324     Convert a floating point constant to the corresponding signed
2325     integer constant. TYPE must be a scalar or vector integer type. CST
2326     must be of scalar or vector floating point type. Both CST and TYPE
2327     must be scalars, or vectors of the same number of elements. If the
2328     value won't fit in the integer type, the results are undefined.
2329 ``uitofp (CST to TYPE)``
2330     Convert an unsigned integer constant to the corresponding floating
2331     point constant. TYPE must be a scalar or vector floating point type.
2332     CST must be of scalar or vector integer type. Both CST and TYPE must
2333     be scalars, or vectors of the same number of elements. If the value
2334     won't fit in the floating point type, the results are undefined.
2335 ``sitofp (CST to TYPE)``
2336     Convert a signed integer constant to the corresponding floating
2337     point constant. TYPE must be a scalar or vector floating point type.
2338     CST must be of scalar or vector integer type. Both CST and TYPE must
2339     be scalars, or vectors of the same number of elements. If the value
2340     won't fit in the floating point type, the results are undefined.
2341 ``ptrtoint (CST to TYPE)``
2342     Convert a pointer typed constant to the corresponding integer
2343     constant. ``TYPE`` must be an integer type. ``CST`` must be of
2344     pointer type. The ``CST`` value is zero extended, truncated, or
2345     unchanged to make it fit in ``TYPE``.
2346 ``inttoptr (CST to TYPE)``
2347     Convert an integer constant to a pointer constant. TYPE must be a
2348     pointer type. CST must be of integer type. The CST value is zero
2349     extended, truncated, or unchanged to make it fit in a pointer size.
2350     This one is *really* dangerous!
2351 ``bitcast (CST to TYPE)``
2352     Convert a constant, CST, to another TYPE. The constraints of the
2353     operands are the same as those for the :ref:`bitcast
2354     instruction <i_bitcast>`.
2355 ``getelementptr (CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)``
2356     Perform the :ref:`getelementptr operation <i_getelementptr>` on
2357     constants. As with the :ref:`getelementptr <i_getelementptr>`
2358     instruction, the index list may have zero or more indexes, which are
2359     required to make sense for the type of "CSTPTR".
2360 ``select (COND, VAL1, VAL2)``
2361     Perform the :ref:`select operation <i_select>` on constants.
2362 ``icmp COND (VAL1, VAL2)``
2363     Performs the :ref:`icmp operation <i_icmp>` on constants.
2364 ``fcmp COND (VAL1, VAL2)``
2365     Performs the :ref:`fcmp operation <i_fcmp>` on constants.
2366 ``extractelement (VAL, IDX)``
2367     Perform the :ref:`extractelement operation <i_extractelement>` on
2368     constants.
2369 ``insertelement (VAL, ELT, IDX)``
2370     Perform the :ref:`insertelement operation <i_insertelement>` on
2371     constants.
2372 ``shufflevector (VEC1, VEC2, IDXMASK)``
2373     Perform the :ref:`shufflevector operation <i_shufflevector>` on
2374     constants.
2375 ``extractvalue (VAL, IDX0, IDX1, ...)``
2376     Perform the :ref:`extractvalue operation <i_extractvalue>` on
2377     constants. The index list is interpreted in a similar manner as
2378     indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At
2379     least one index value must be specified.
2380 ``insertvalue (VAL, ELT, IDX0, IDX1, ...)``
2381     Perform the :ref:`insertvalue operation <i_insertvalue>` on constants.
2382     The index list is interpreted in a similar manner as indices in a
2383     ':ref:`getelementptr <i_getelementptr>`' operation. At least one index
2384     value must be specified.
2385 ``OPCODE (LHS, RHS)``
2386     Perform the specified operation of the LHS and RHS constants. OPCODE
2387     may be any of the :ref:`binary <binaryops>` or :ref:`bitwise
2388     binary <bitwiseops>` operations. The constraints on operands are
2389     the same as those for the corresponding instruction (e.g. no bitwise
2390     operations on floating point values are allowed).
2391
2392 Other Values
2393 ============
2394
2395 .. _inlineasmexprs:
2396
2397 Inline Assembler Expressions
2398 ----------------------------
2399
2400 LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level
2401 Inline Assembly <moduleasm>`) through the use of a special value. This
2402 value represents the inline assembler as a string (containing the
2403 instructions to emit), a list of operand constraints (stored as a
2404 string), a flag that indicates whether or not the inline asm expression
2405 has side effects, and a flag indicating whether the function containing
2406 the asm needs to align its stack conservatively. An example inline
2407 assembler expression is:
2408
2409 .. code-block:: llvm
2410
2411     i32 (i32) asm "bswap $0", "=r,r"
2412
2413 Inline assembler expressions may **only** be used as the callee operand
2414 of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction.
2415 Thus, typically we have:
2416
2417 .. code-block:: llvm
2418
2419     %X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
2420
2421 Inline asms with side effects not visible in the constraint list must be
2422 marked as having side effects. This is done through the use of the
2423 '``sideeffect``' keyword, like so:
2424
2425 .. code-block:: llvm
2426
2427     call void asm sideeffect "eieio", ""()
2428
2429 In some cases inline asms will contain code that will not work unless
2430 the stack is aligned in some way, such as calls or SSE instructions on
2431 x86, yet will not contain code that does that alignment within the asm.
2432 The compiler should make conservative assumptions about what the asm
2433 might contain and should generate its usual stack alignment code in the
2434 prologue if the '``alignstack``' keyword is present:
2435
2436 .. code-block:: llvm
2437
2438     call void asm alignstack "eieio", ""()
2439
2440 Inline asms also support using non-standard assembly dialects. The
2441 assumed dialect is ATT. When the '``inteldialect``' keyword is present,
2442 the inline asm is using the Intel dialect. Currently, ATT and Intel are
2443 the only supported dialects. An example is:
2444
2445 .. code-block:: llvm
2446
2447     call void asm inteldialect "eieio", ""()
2448
2449 If multiple keywords appear the '``sideeffect``' keyword must come
2450 first, the '``alignstack``' keyword second and the '``inteldialect``'
2451 keyword last.
2452
2453 Inline Asm Metadata
2454 ^^^^^^^^^^^^^^^^^^^
2455
2456 The call instructions that wrap inline asm nodes may have a
2457 "``!srcloc``" MDNode attached to it that contains a list of constant
2458 integers. If present, the code generator will use the integer as the
2459 location cookie value when report errors through the ``LLVMContext``
2460 error reporting mechanisms. This allows a front-end to correlate backend
2461 errors that occur with inline asm back to the source code that produced
2462 it. For example:
2463
2464 .. code-block:: llvm
2465
2466     call void asm sideeffect "something bad", ""(), !srcloc !42
2467     ...
2468     !42 = !{ i32 1234567 }
2469
2470 It is up to the front-end to make sense of the magic numbers it places
2471 in the IR. If the MDNode contains multiple constants, the code generator
2472 will use the one that corresponds to the line of the asm that the error
2473 occurs on.
2474
2475 .. _metadata:
2476
2477 Metadata Nodes and Metadata Strings
2478 -----------------------------------
2479
2480 LLVM IR allows metadata to be attached to instructions in the program
2481 that can convey extra information about the code to the optimizers and
2482 code generator. One example application of metadata is source-level
2483 debug information. There are two metadata primitives: strings and nodes.
2484 All metadata has the ``metadata`` type and is identified in syntax by a
2485 preceding exclamation point ('``!``').
2486
2487 A metadata string is a string surrounded by double quotes. It can
2488 contain any character by escaping non-printable characters with
2489 "``\xx``" where "``xx``" is the two digit hex code. For example:
2490 "``!"test\00"``".
2491
2492 Metadata nodes are represented with notation similar to structure
2493 constants (a comma separated list of elements, surrounded by braces and
2494 preceded by an exclamation point). Metadata nodes can have any values as
2495 their operand. For example:
2496
2497 .. code-block:: llvm
2498
2499     !{ metadata !"test\00", i32 10}
2500
2501 A :ref:`named metadata <namedmetadatastructure>` is a collection of
2502 metadata nodes, which can be looked up in the module symbol table. For
2503 example:
2504
2505 .. code-block:: llvm
2506
2507     !foo =  metadata !{!4, !3}
2508
2509 Metadata can be used as function arguments. Here ``llvm.dbg.value``
2510 function is using two metadata arguments:
2511
2512 .. code-block:: llvm
2513
2514     call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
2515
2516 Metadata can be attached with an instruction. Here metadata ``!21`` is
2517 attached to the ``add`` instruction using the ``!dbg`` identifier:
2518
2519 .. code-block:: llvm
2520
2521     %indvar.next = add i64 %indvar, 1, !dbg !21
2522
2523 More information about specific metadata nodes recognized by the
2524 optimizers and code generator is found below.
2525
2526 '``tbaa``' Metadata
2527 ^^^^^^^^^^^^^^^^^^^
2528
2529 In LLVM IR, memory does not have types, so LLVM's own type system is not
2530 suitable for doing TBAA. Instead, metadata is added to the IR to
2531 describe a type system of a higher level language. This can be used to
2532 implement typical C/C++ TBAA, but it can also be used to implement
2533 custom alias analysis behavior for other languages.
2534
2535 The current metadata format is very simple. TBAA metadata nodes have up
2536 to three fields, e.g.:
2537
2538 .. code-block:: llvm
2539
2540     !0 = metadata !{ metadata !"an example type tree" }
2541     !1 = metadata !{ metadata !"int", metadata !0 }
2542     !2 = metadata !{ metadata !"float", metadata !0 }
2543     !3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
2544
2545 The first field is an identity field. It can be any value, usually a
2546 metadata string, which uniquely identifies the type. The most important
2547 name in the tree is the name of the root node. Two trees with different
2548 root node names are entirely disjoint, even if they have leaves with
2549 common names.
2550
2551 The second field identifies the type's parent node in the tree, or is
2552 null or omitted for a root node. A type is considered to alias all of
2553 its descendants and all of its ancestors in the tree. Also, a type is
2554 considered to alias all types in other trees, so that bitcode produced
2555 from multiple front-ends is handled conservatively.
2556
2557 If the third field is present, it's an integer which if equal to 1
2558 indicates that the type is "constant" (meaning
2559 ``pointsToConstantMemory`` should return true; see `other useful
2560 AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_).
2561
2562 '``tbaa.struct``' Metadata
2563 ^^^^^^^^^^^^^^^^^^^^^^^^^^
2564
2565 The :ref:`llvm.memcpy <int_memcpy>` is often used to implement
2566 aggregate assignment operations in C and similar languages, however it
2567 is defined to copy a contiguous region of memory, which is more than
2568 strictly necessary for aggregate types which contain holes due to
2569 padding. Also, it doesn't contain any TBAA information about the fields
2570 of the aggregate.
2571
2572 ``!tbaa.struct`` metadata can describe which memory subregions in a
2573 memcpy are padding and what the TBAA tags of the struct are.
2574
2575 The current metadata format is very simple. ``!tbaa.struct`` metadata
2576 nodes are a list of operands which are in conceptual groups of three.
2577 For each group of three, the first operand gives the byte offset of a
2578 field in bytes, the second gives its size in bytes, and the third gives
2579 its tbaa tag. e.g.:
2580
2581 .. code-block:: llvm
2582
2583     !4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }
2584
2585 This describes a struct with two fields. The first is at offset 0 bytes
2586 with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
2587 and has size 4 bytes and has tbaa tag !2.
2588
2589 Note that the fields need not be contiguous. In this example, there is a
2590 4 byte gap between the two fields. This gap represents padding which
2591 does not carry useful data and need not be preserved.
2592
2593 '``fpmath``' Metadata
2594 ^^^^^^^^^^^^^^^^^^^^^
2595
2596 ``fpmath`` metadata may be attached to any instruction of floating point
2597 type. It can be used to express the maximum acceptable error in the
2598 result of that instruction, in ULPs, thus potentially allowing the
2599 compiler to use a more efficient but less accurate method of computing
2600 it. ULP is defined as follows:
2601
2602     If ``x`` is a real number that lies between two finite consecutive
2603     floating-point numbers ``a`` and ``b``, without being equal to one
2604     of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the
2605     distance between the two non-equal finite floating-point numbers
2606     nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``.
2607
2608 The metadata node shall consist of a single positive floating point
2609 number representing the maximum relative error, for example:
2610
2611 .. code-block:: llvm
2612
2613     !0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
2614
2615 '``range``' Metadata
2616 ^^^^^^^^^^^^^^^^^^^^
2617
2618 ``range`` metadata may be attached only to loads of integer types. It
2619 expresses the possible ranges the loaded value is in. The ranges are
2620 represented with a flattened list of integers. The loaded value is known
2621 to be in the union of the ranges defined by each consecutive pair. Each
2622 pair has the following properties:
2623
2624 -  The type must match the type loaded by the instruction.
2625 -  The pair ``a,b`` represents the range ``[a,b)``.
2626 -  Both ``a`` and ``b`` are constants.
2627 -  The range is allowed to wrap.
2628 -  The range should not represent the full or empty set. That is,
2629    ``a!=b``.
2630
2631 In addition, the pairs must be in signed order of the lower bound and
2632 they must be non-contiguous.
2633
2634 Examples:
2635
2636 .. code-block:: llvm
2637
2638       %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
2639       %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
2640       %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
2641       %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5
2642     ...
2643     !0 = metadata !{ i8 0, i8 2 }
2644     !1 = metadata !{ i8 255, i8 2 }
2645     !2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
2646     !3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
2647
2648 '``llvm.loop``'
2649 ^^^^^^^^^^^^^^^
2650
2651 It is sometimes useful to attach information to loop constructs. Currently,
2652 loop metadata is implemented as metadata attached to the branch instruction
2653 in the loop latch block. This type of metadata refer to a metadata node that is
2654 guaranteed to be separate for each loop. The loop identifier metadata is
2655 specified with the name ``llvm.loop``.
2656
2657 The loop identifier metadata is implemented using a metadata that refers to
2658 itself to avoid merging it with any other identifier metadata, e.g.,
2659 during module linkage or function inlining. That is, each loop should refer
2660 to their own identification metadata even if they reside in separate functions.
2661 The following example contains loop identifier metadata for two separate loop
2662 constructs:
2663
2664 .. code-block:: llvm
2665
2666     !0 = metadata !{ metadata !0 }
2667     !1 = metadata !{ metadata !1 }
2668
2669 The loop identifier metadata can be used to specify additional per-loop
2670 metadata. Any operands after the first operand can be treated as user-defined
2671 metadata. For example the ``llvm.vectorizer.unroll`` metadata is understood
2672 by the loop vectorizer to indicate how many times to unroll the loop:
2673
2674 .. code-block:: llvm
2675
2676       br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
2677     ...
2678     !0 = metadata !{ metadata !0, metadata !1 }
2679     !1 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 2 }
2680
2681 '``llvm.mem``'
2682 ^^^^^^^^^^^^^^^
2683
2684 Metadata types used to annotate memory accesses with information helpful
2685 for optimizations are prefixed with ``llvm.mem``.
2686
2687 '``llvm.mem.parallel_loop_access``' Metadata
2688 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2689
2690 For a loop to be parallel, in addition to using
2691 the ``llvm.loop`` metadata to mark the loop latch branch instruction,
2692 also all of the memory accessing instructions in the loop body need to be
2693 marked with the ``llvm.mem.parallel_loop_access`` metadata. If there
2694 is at least one memory accessing instruction not marked with the metadata,
2695 the loop must be considered a sequential loop. This causes parallel loops to be
2696 converted to sequential loops due to optimization passes that are unaware of
2697 the parallel semantics and that insert new memory instructions to the loop
2698 body.
2699
2700 Example of a loop that is considered parallel due to its correct use of
2701 both ``llvm.loop`` and ``llvm.mem.parallel_loop_access``
2702 metadata types that refer to the same loop identifier metadata.
2703
2704 .. code-block:: llvm
2705
2706    for.body:
2707      ...
2708      %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
2709      ...
2710      store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
2711      ...
2712      br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0
2713
2714    for.end:
2715    ...
2716    !0 = metadata !{ metadata !0 }
2717
2718 It is also possible to have nested parallel loops. In that case the
2719 memory accesses refer to a list of loop identifier metadata nodes instead of
2720 the loop identifier metadata node directly:
2721
2722 .. code-block:: llvm
2723
2724    outer.for.body:
2725    ...
2726
2727    inner.for.body:
2728      ...
2729      %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
2730      ...
2731      store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
2732      ...
2733      br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1
2734
2735    inner.for.end:
2736      ...
2737      %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
2738      ...
2739      store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
2740      ...
2741      br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
2742
2743    outer.for.end:                                          ; preds = %for.body
2744    ...
2745    !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers
2746    !1 = metadata !{ metadata !1 } ; an identifier for the inner loop
2747    !2 = metadata !{ metadata !2 } ; an identifier for the outer loop
2748
2749 '``llvm.vectorizer``'
2750 ^^^^^^^^^^^^^^^^^^^^^
2751
2752 Metadata prefixed with ``llvm.vectorizer`` is used to control per-loop
2753 vectorization parameters such as vectorization factor and unroll factor.
2754
2755 ``llvm.vectorizer`` metadata should be used in conjunction with ``llvm.loop``
2756 loop identification metadata.
2757
2758 '``llvm.vectorizer.unroll``' Metadata
2759 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2760
2761 This metadata instructs the loop vectorizer to unroll the specified
2762 loop exactly ``N`` times.
2763
2764 The first operand is the string ``llvm.vectorizer.unroll`` and the second
2765 operand is an integer specifying the unroll factor. For example:
2766
2767 .. code-block:: llvm
2768
2769    !0 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 4 }
2770
2771 Note that setting ``llvm.vectorizer.unroll`` to 1 disables unrolling of the
2772 loop.
2773
2774 If ``llvm.vectorizer.unroll`` is set to 0 then the amount of unrolling will be
2775 determined automatically.
2776
2777 '``llvm.vectorizer.width``' Metadata
2778 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2779
2780 This metadata sets the target width of the vectorizer to ``N``. Without
2781 this metadata, the vectorizer will choose a width automatically.
2782 Regardless of this metadata, the vectorizer will only vectorize loops if
2783 it believes it is valid to do so.
2784
2785 The first operand is the string ``llvm.vectorizer.width`` and the second
2786 operand is an integer specifying the width. For example:
2787
2788 .. code-block:: llvm
2789
2790    !0 = metadata !{ metadata !"llvm.vectorizer.width", i32 4 }
2791
2792 Note that setting ``llvm.vectorizer.width`` to 1 disables vectorization of the
2793 loop.
2794
2795 If ``llvm.vectorizer.width`` is set to 0 then the width will be determined
2796 automatically.
2797
2798 Module Flags Metadata
2799 =====================
2800
2801 Information about the module as a whole is difficult to convey to LLVM's
2802 subsystems. The LLVM IR isn't sufficient to transmit this information.
2803 The ``llvm.module.flags`` named metadata exists in order to facilitate
2804 this. These flags are in the form of key / value pairs --- much like a
2805 dictionary --- making it easy for any subsystem who cares about a flag to
2806 look it up.
2807
2808 The ``llvm.module.flags`` metadata contains a list of metadata triplets.
2809 Each triplet has the following form:
2810
2811 -  The first element is a *behavior* flag, which specifies the behavior
2812    when two (or more) modules are merged together, and it encounters two
2813    (or more) metadata with the same ID. The supported behaviors are
2814    described below.
2815 -  The second element is a metadata string that is a unique ID for the
2816    metadata. Each module may only have one flag entry for each unique ID (not
2817    including entries with the **Require** behavior).
2818 -  The third element is the value of the flag.
2819
2820 When two (or more) modules are merged together, the resulting
2821 ``llvm.module.flags`` metadata is the union of the modules' flags. That is, for
2822 each unique metadata ID string, there will be exactly one entry in the merged
2823 modules ``llvm.module.flags`` metadata table, and the value for that entry will
2824 be determined by the merge behavior flag, as described below. The only exception
2825 is that entries with the *Require* behavior are always preserved.
2826
2827 The following behaviors are supported:
2828
2829 .. list-table::
2830    :header-rows: 1
2831    :widths: 10 90
2832
2833    * - Value
2834      - Behavior
2835
2836    * - 1
2837      - **Error**
2838            Emits an error if two values disagree, otherwise the resulting value
2839            is that of the operands.
2840
2841    * - 2
2842      - **Warning**
2843            Emits a warning if two values disagree. The result value will be the
2844            operand for the flag from the first module being linked.
2845
2846    * - 3
2847      - **Require**
2848            Adds a requirement that another module flag be present and have a
2849            specified value after linking is performed. The value must be a
2850            metadata pair, where the first element of the pair is the ID of the
2851            module flag to be restricted, and the second element of the pair is
2852            the value the module flag should be restricted to. This behavior can
2853            be used to restrict the allowable results (via triggering of an
2854            error) of linking IDs with the **Override** behavior.
2855
2856    * - 4
2857      - **Override**
2858            Uses the specified value, regardless of the behavior or value of the
2859            other module. If both modules specify **Override**, but the values
2860            differ, an error will be emitted.
2861
2862    * - 5
2863      - **Append**
2864            Appends the two values, which are required to be metadata nodes.
2865
2866    * - 6
2867      - **AppendUnique**
2868            Appends the two values, which are required to be metadata
2869            nodes. However, duplicate entries in the second list are dropped
2870            during the append operation.
2871
2872 It is an error for a particular unique flag ID to have multiple behaviors,
2873 except in the case of **Require** (which adds restrictions on another metadata
2874 value) or **Override**.
2875
2876 An example of module flags:
2877
2878 .. code-block:: llvm
2879
2880     !0 = metadata !{ i32 1, metadata !"foo", i32 1 }
2881     !1 = metadata !{ i32 4, metadata !"bar", i32 37 }
2882     !2 = metadata !{ i32 2, metadata !"qux", i32 42 }
2883     !3 = metadata !{ i32 3, metadata !"qux",
2884       metadata !{
2885         metadata !"foo", i32 1
2886       }
2887     }
2888     !llvm.module.flags = !{ !0, !1, !2, !3 }
2889
2890 -  Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior
2891    if two or more ``!"foo"`` flags are seen is to emit an error if their
2892    values are not equal.
2893
2894 -  Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The
2895    behavior if two or more ``!"bar"`` flags are seen is to use the value
2896    '37'.
2897
2898 -  Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The
2899    behavior if two or more ``!"qux"`` flags are seen is to emit a
2900    warning if their values are not equal.
2901
2902 -  Metadata ``!3`` has the ID ``!"qux"`` and the value:
2903
2904    ::
2905
2906        metadata !{ metadata !"foo", i32 1 }
2907
2908    The behavior is to emit an error if the ``llvm.module.flags`` does not
2909    contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
2910    performed.
2911
2912 Objective-C Garbage Collection Module Flags Metadata
2913 ----------------------------------------------------
2914
2915 On the Mach-O platform, Objective-C stores metadata about garbage
2916 collection in a special section called "image info". The metadata
2917 consists of a version number and a bitmask specifying what types of
2918 garbage collection are supported (if any) by the file. If two or more
2919 modules are linked together their garbage collection metadata needs to
2920 be merged rather than appended together.
2921
2922 The Objective-C garbage collection module flags metadata consists of the
2923 following key-value pairs:
2924
2925 .. list-table::
2926    :header-rows: 1
2927    :widths: 30 70
2928
2929    * - Key
2930      - Value
2931
2932    * - ``Objective-C Version``
2933      - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2.
2934
2935    * - ``Objective-C Image Info Version``
2936      - **[Required]** --- The version of the image info section. Currently
2937        always 0.
2938
2939    * - ``Objective-C Image Info Section``
2940      - **[Required]** --- The section to place the metadata. Valid values are
2941        ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and
2942        ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for
2943        Objective-C ABI version 2.
2944
2945    * - ``Objective-C Garbage Collection``
2946      - **[Required]** --- Specifies whether garbage collection is supported or
2947        not. Valid values are 0, for no garbage collection, and 2, for garbage
2948        collection supported.
2949
2950    * - ``Objective-C GC Only``
2951      - **[Optional]** --- Specifies that only garbage collection is supported.
2952        If present, its value must be 6. This flag requires that the
2953        ``Objective-C Garbage Collection`` flag have the value 2.
2954
2955 Some important flag interactions:
2956
2957 -  If a module with ``Objective-C Garbage Collection`` set to 0 is
2958    merged with a module with ``Objective-C Garbage Collection`` set to
2959    2, then the resulting module has the
2960    ``Objective-C Garbage Collection`` flag set to 0.
2961 -  A module with ``Objective-C Garbage Collection`` set to 0 cannot be
2962    merged with a module with ``Objective-C GC Only`` set to 6.
2963
2964 Automatic Linker Flags Module Flags Metadata
2965 --------------------------------------------
2966
2967 Some targets support embedding flags to the linker inside individual object
2968 files. Typically this is used in conjunction with language extensions which
2969 allow source files to explicitly declare the libraries they depend on, and have
2970 these automatically be transmitted to the linker via object files.
2971
2972 These flags are encoded in the IR using metadata in the module flags section,
2973 using the ``Linker Options`` key. The merge behavior for this flag is required
2974 to be ``AppendUnique``, and the value for the key is expected to be a metadata
2975 node which should be a list of other metadata nodes, each of which should be a
2976 list of metadata strings defining linker options.
2977
2978 For example, the following metadata section specifies two separate sets of
2979 linker options, presumably to link against ``libz`` and the ``Cocoa``
2980 framework::
2981
2982     !0 = metadata !{ i32 6, metadata !"Linker Options",
2983        metadata !{
2984           metadata !{ metadata !"-lz" },
2985           metadata !{ metadata !"-framework", metadata !"Cocoa" } } }
2986     !llvm.module.flags = !{ !0 }
2987
2988 The metadata encoding as lists of lists of options, as opposed to a collapsed
2989 list of options, is chosen so that the IR encoding can use multiple option
2990 strings to specify e.g., a single library, while still having that specifier be
2991 preserved as an atomic element that can be recognized by a target specific
2992 assembly writer or object file emitter.
2993
2994 Each individual option is required to be either a valid option for the target's
2995 linker, or an option that is reserved by the target specific assembly writer or
2996 object file emitter. No other aspect of these options is defined by the IR.
2997
2998 .. _intrinsicglobalvariables:
2999
3000 Intrinsic Global Variables
3001 ==========================
3002
3003 LLVM has a number of "magic" global variables that contain data that
3004 affect code generation or other IR semantics. These are documented here.
3005 All globals of this sort should have a section specified as
3006 "``llvm.metadata``". This section and all globals that start with
3007 "``llvm.``" are reserved for use by LLVM.
3008
3009 .. _gv_llvmused:
3010
3011 The '``llvm.used``' Global Variable
3012 -----------------------------------
3013
3014 The ``@llvm.used`` global is an array which has
3015 :ref:`appending linkage <linkage_appending>`. This array contains a list of
3016 pointers to named global variables, functions and aliases which may optionally
3017 have a pointer cast formed of bitcast or getelementptr. For example, a legal
3018 use of it is:
3019
3020 .. code-block:: llvm
3021
3022     @X = global i8 4
3023     @Y = global i32 123
3024
3025     @llvm.used = appending global [2 x i8*] [
3026        i8* @X,
3027        i8* bitcast (i32* @Y to i8*)
3028     ], section "llvm.metadata"
3029
3030 If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler,
3031 and linker are required to treat the symbol as if there is a reference to the
3032 symbol that it cannot see (which is why they have to be named). For example, if
3033 a variable has internal linkage and no references other than that from the
3034 ``@llvm.used`` list, it cannot be deleted. This is commonly used to represent
3035 references from inline asms and other things the compiler cannot "see", and
3036 corresponds to "``attribute((used))``" in GNU C.
3037
3038 On some targets, the code generator must emit a directive to the
3039 assembler or object file to prevent the assembler and linker from
3040 molesting the symbol.
3041
3042 .. _gv_llvmcompilerused:
3043
3044 The '``llvm.compiler.used``' Global Variable
3045 --------------------------------------------
3046
3047 The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used``
3048 directive, except that it only prevents the compiler from touching the
3049 symbol. On targets that support it, this allows an intelligent linker to
3050 optimize references to the symbol without being impeded as it would be
3051 by ``@llvm.used``.
3052
3053 This is a rare construct that should only be used in rare circumstances,
3054 and should not be exposed to source languages.
3055
3056 .. _gv_llvmglobalctors:
3057
3058 The '``llvm.global_ctors``' Global Variable
3059 -------------------------------------------
3060
3061 .. code-block:: llvm
3062
3063     %0 = type { i32, void ()* }
3064     @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
3065
3066 The ``@llvm.global_ctors`` array contains a list of constructor
3067 functions and associated priorities. The functions referenced by this
3068 array will be called in ascending order of priority (i.e. lowest first)
3069 when the module is loaded. The order of functions with the same priority
3070 is not defined.
3071
3072 .. _llvmglobaldtors:
3073
3074 The '``llvm.global_dtors``' Global Variable
3075 -------------------------------------------
3076
3077 .. code-block:: llvm
3078
3079     %0 = type { i32, void ()* }
3080     @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
3081
3082 The ``@llvm.global_dtors`` array contains a list of destructor functions
3083 and associated priorities. The functions referenced by this array will
3084 be called in descending order of priority (i.e. highest first) when the
3085 module is loaded. The order of functions with the same priority is not
3086 defined.
3087
3088 Instruction Reference
3089 =====================
3090
3091 The LLVM instruction set consists of several different classifications
3092 of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
3093 instructions <binaryops>`, :ref:`bitwise binary
3094 instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
3095 :ref:`other instructions <otherops>`.
3096
3097 .. _terminators:
3098
3099 Terminator Instructions
3100 -----------------------
3101
3102 As mentioned :ref:`previously <functionstructure>`, every basic block in a
3103 program ends with a "Terminator" instruction, which indicates which
3104 block should be executed after the current block is finished. These
3105 terminator instructions typically yield a '``void``' value: they produce
3106 control flow, not values (the one exception being the
3107 ':ref:`invoke <i_invoke>`' instruction).
3108
3109 The terminator instructions are: ':ref:`ret <i_ret>`',
3110 ':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
3111 ':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
3112 ':ref:`resume <i_resume>`', and ':ref:`unreachable <i_unreachable>`'.
3113
3114 .. _i_ret:
3115
3116 '``ret``' Instruction
3117 ^^^^^^^^^^^^^^^^^^^^^
3118
3119 Syntax:
3120 """""""
3121
3122 ::
3123
3124       ret <type> <value>       ; Return a value from a non-void function
3125       ret void                 ; Return from void function
3126
3127 Overview:
3128 """""""""
3129
3130 The '``ret``' instruction is used to return control flow (and optionally
3131 a value) from a function back to the caller.
3132
3133 There are two forms of the '``ret``' instruction: one that returns a
3134 value and then causes control flow, and one that just causes control
3135 flow to occur.
3136
3137 Arguments:
3138 """"""""""
3139
3140 The '``ret``' instruction optionally accepts a single argument, the
3141 return value. The type of the return value must be a ':ref:`first
3142 class <t_firstclass>`' type.
3143
3144 A function is not :ref:`well formed <wellformed>` if it it has a non-void
3145 return type and contains a '``ret``' instruction with no return value or
3146 a return value with a type that does not match its type, or if it has a
3147 void return type and contains a '``ret``' instruction with a return
3148 value.
3149
3150 Semantics:
3151 """"""""""
3152
3153 When the '``ret``' instruction is executed, control flow returns back to
3154 the calling function's context. If the caller is a
3155 ":ref:`call <i_call>`" instruction, execution continues at the
3156 instruction after the call. If the caller was an
3157 ":ref:`invoke <i_invoke>`" instruction, execution continues at the
3158 beginning of the "normal" destination block. If the instruction returns
3159 a value, that value shall set the call or invoke instruction's return
3160 value.
3161
3162 Example:
3163 """"""""
3164
3165 .. code-block:: llvm
3166
3167       ret i32 5                       ; Return an integer value of 5
3168       ret void                        ; Return from a void function
3169       ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
3170
3171 .. _i_br:
3172
3173 '``br``' Instruction
3174 ^^^^^^^^^^^^^^^^^^^^
3175
3176 Syntax:
3177 """""""
3178
3179 ::
3180
3181       br i1 <cond>, label <iftrue>, label <iffalse>
3182       br label <dest>          ; Unconditional branch
3183
3184 Overview:
3185 """""""""
3186
3187 The '``br``' instruction is used to cause control flow to transfer to a
3188 different basic block in the current function. There are two forms of
3189 this instruction, corresponding to a conditional branch and an
3190 unconditional branch.
3191
3192 Arguments:
3193 """"""""""
3194
3195 The conditional branch form of the '``br``' instruction takes a single
3196 '``i1``' value and two '``label``' values. The unconditional form of the
3197 '``br``' instruction takes a single '``label``' value as a target.
3198
3199 Semantics:
3200 """"""""""
3201
3202 Upon execution of a conditional '``br``' instruction, the '``i1``'
3203 argument is evaluated. If the value is ``true``, control flows to the
3204 '``iftrue``' ``label`` argument. If "cond" is ``false``, control flows
3205 to the '``iffalse``' ``label`` argument.
3206
3207 Example:
3208 """"""""
3209
3210 .. code-block:: llvm
3211
3212     Test:
3213       %cond = icmp eq i32 %a, %b
3214       br i1 %cond, label %IfEqual, label %IfUnequal
3215     IfEqual:
3216       ret i32 1
3217     IfUnequal:
3218       ret i32 0
3219
3220 .. _i_switch:
3221
3222 '``switch``' Instruction
3223 ^^^^^^^^^^^^^^^^^^^^^^^^
3224
3225 Syntax:
3226 """""""
3227
3228 ::
3229
3230       switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
3231
3232 Overview:
3233 """""""""
3234
3235 The '``switch``' instruction is used to transfer control flow to one of
3236 several different places. It is a generalization of the '``br``'
3237 instruction, allowing a branch to occur to one of many possible
3238 destinations.
3239
3240 Arguments:
3241 """"""""""
3242
3243 The '``switch``' instruction uses three parameters: an integer
3244 comparison value '``value``', a default '``label``' destination, and an
3245 array of pairs of comparison value constants and '``label``'s. The table
3246 is not allowed to contain duplicate constant entries.
3247
3248 Semantics:
3249 """"""""""
3250
3251 The ``switch`` instruction specifies a table of values and destinations.
3252 When the '``switch``' instruction is executed, this table is searched
3253 for the given value. If the value is found, control flow is transferred
3254 to the corresponding destination; otherwise, control flow is transferred
3255 to the default destination.
3256
3257 Implementation:
3258 """""""""""""""
3259
3260 Depending on properties of the target machine and the particular
3261 ``switch`` instruction, this instruction may be code generated in
3262 different ways. For example, it could be generated as a series of
3263 chained conditional branches or with a lookup table.
3264
3265 Example:
3266 """"""""
3267
3268 .. code-block:: llvm
3269
3270      ; Emulate a conditional br instruction
3271      %Val = zext i1 %value to i32
3272      switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
3273
3274      ; Emulate an unconditional br instruction
3275      switch i32 0, label %dest [ ]
3276
3277      ; Implement a jump table:
3278      switch i32 %val, label %otherwise [ i32 0, label %onzero
3279                                          i32 1, label %onone
3280                                          i32 2, label %ontwo ]
3281
3282 .. _i_indirectbr:
3283
3284 '``indirectbr``' Instruction
3285 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3286
3287 Syntax:
3288 """""""
3289
3290 ::
3291
3292       indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
3293
3294 Overview:
3295 """""""""
3296
3297 The '``indirectbr``' instruction implements an indirect branch to a
3298 label within the current function, whose address is specified by
3299 "``address``". Address must be derived from a
3300 :ref:`blockaddress <blockaddress>` constant.
3301
3302 Arguments:
3303 """"""""""
3304
3305 The '``address``' argument is the address of the label to jump to. The
3306 rest of the arguments indicate the full set of possible destinations
3307 that the address may point to. Blocks are allowed to occur multiple
3308 times in the destination list, though this isn't particularly useful.
3309
3310 This destination list is required so that dataflow analysis has an
3311 accurate understanding of the CFG.
3312
3313 Semantics:
3314 """"""""""
3315
3316 Control transfers to the block specified in the address argument. All
3317 possible destination blocks must be listed in the label list, otherwise
3318 this instruction has undefined behavior. This implies that jumps to
3319 labels defined in other functions have undefined behavior as well.
3320
3321 Implementation:
3322 """""""""""""""
3323
3324 This is typically implemented with a jump through a register.
3325
3326 Example:
3327 """"""""
3328
3329 .. code-block:: llvm
3330
3331      indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
3332
3333 .. _i_invoke:
3334
3335 '``invoke``' Instruction
3336 ^^^^^^^^^^^^^^^^^^^^^^^^
3337
3338 Syntax:
3339 """""""
3340
3341 ::
3342
3343       <result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs]
3344                     to label <normal label> unwind label <exception label>
3345
3346 Overview:
3347 """""""""
3348
3349 The '``invoke``' instruction causes control to transfer to a specified
3350 function, with the possibility of control flow transfer to either the
3351 '``normal``' label or the '``exception``' label. If the callee function
3352 returns with the "``ret``" instruction, control flow will return to the
3353 "normal" label. If the callee (or any indirect callees) returns via the
3354 ":ref:`resume <i_resume>`" instruction or other exception handling
3355 mechanism, control is interrupted and continued at the dynamically
3356 nearest "exception" label.
3357
3358 The '``exception``' label is a `landing
3359 pad <ExceptionHandling.html#overview>`_ for the exception. As such,
3360 '``exception``' label is required to have the
3361 ":ref:`landingpad <i_landingpad>`" instruction, which contains the
3362 information about the behavior of the program after unwinding happens,
3363 as its first non-PHI instruction. The restrictions on the
3364 "``landingpad``" instruction's tightly couples it to the "``invoke``"
3365 instruction, so that the important information contained within the
3366 "``landingpad``" instruction can't be lost through normal code motion.
3367
3368 Arguments:
3369 """"""""""
3370
3371 This instruction requires several arguments:
3372
3373 #. The optional "cconv" marker indicates which :ref:`calling
3374    convention <callingconv>` the call should use. If none is
3375    specified, the call defaults to using C calling conventions.
3376 #. The optional :ref:`Parameter Attributes <paramattrs>` list for return
3377    values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
3378    are valid here.
3379 #. '``ptr to function ty``': shall be the signature of the pointer to
3380    function value being invoked. In most cases, this is a direct
3381    function invocation, but indirect ``invoke``'s are just as possible,
3382    branching off an arbitrary pointer to function value.
3383 #. '``function ptr val``': An LLVM value containing a pointer to a
3384    function to be invoked.
3385 #. '``function args``': argument list whose types match the function
3386    signature argument types and parameter attributes. All arguments must
3387    be of :ref:`first class <t_firstclass>` type. If the function signature
3388    indicates the function accepts a variable number of arguments, the
3389    extra arguments can be specified.
3390 #. '``normal label``': the label reached when the called function
3391    executes a '``ret``' instruction.
3392 #. '``exception label``': the label reached when a callee returns via
3393    the :ref:`resume <i_resume>` instruction or other exception handling
3394    mechanism.
3395 #. The optional :ref:`function attributes <fnattrs>` list. Only
3396    '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
3397    attributes are valid here.
3398
3399 Semantics:
3400 """"""""""
3401
3402 This instruction is designed to operate as a standard '``call``'
3403 instruction in most regards. The primary difference is that it
3404 establishes an association with a label, which is used by the runtime
3405 library to unwind the stack.
3406
3407 This instruction is used in languages with destructors to ensure that
3408 proper cleanup is performed in the case of either a ``longjmp`` or a
3409 thrown exception. Additionally, this is important for implementation of
3410 '``catch``' clauses in high-level languages that support them.
3411
3412 For the purposes of the SSA form, the definition of the value returned
3413 by the '``invoke``' instruction is deemed to occur on the edge from the
3414 current block to the "normal" label. If the callee unwinds then no
3415 return value is available.
3416
3417 Example:
3418 """"""""
3419
3420 .. code-block:: llvm
3421
3422       %retval = invoke i32 @Test(i32 15) to label %Continue
3423                   unwind label %TestCleanup              ; {i32}:retval set
3424       %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
3425                   unwind label %TestCleanup              ; {i32}:retval set
3426
3427 .. _i_resume:
3428
3429 '``resume``' Instruction
3430 ^^^^^^^^^^^^^^^^^^^^^^^^
3431
3432 Syntax:
3433 """""""
3434
3435 ::
3436
3437       resume <type> <value>
3438
3439 Overview:
3440 """""""""
3441
3442 The '``resume``' instruction is a terminator instruction that has no
3443 successors.
3444
3445 Arguments:
3446 """"""""""
3447
3448 The '``resume``' instruction requires one argument, which must have the
3449 same type as the result of any '``landingpad``' instruction in the same
3450 function.
3451
3452 Semantics:
3453 """"""""""
3454
3455 The '``resume``' instruction resumes propagation of an existing
3456 (in-flight) exception whose unwinding was interrupted with a
3457 :ref:`landingpad <i_landingpad>` instruction.
3458
3459 Example:
3460 """"""""
3461
3462 .. code-block:: llvm
3463
3464       resume { i8*, i32 } %exn
3465
3466 .. _i_unreachable:
3467
3468 '``unreachable``' Instruction
3469 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3470
3471 Syntax:
3472 """""""
3473
3474 ::
3475
3476       unreachable
3477
3478 Overview:
3479 """""""""
3480
3481 The '``unreachable``' instruction has no defined semantics. This
3482 instruction is used to inform the optimizer that a particular portion of
3483 the code is not reachable. This can be used to indicate that the code
3484 after a no-return function cannot be reached, and other facts.
3485
3486 Semantics:
3487 """"""""""
3488
3489 The '``unreachable``' instruction has no defined semantics.
3490
3491 .. _binaryops:
3492
3493 Binary Operations
3494 -----------------
3495
3496 Binary operators are used to do most of the computation in a program.
3497 They require two operands of the same type, execute an operation on
3498 them, and produce a single value. The operands might represent multiple
3499 data, as is the case with the :ref:`vector <t_vector>` data type. The
3500 result value has the same type as its operands.
3501
3502 There are several different binary operators:
3503
3504 .. _i_add:
3505
3506 '``add``' Instruction
3507 ^^^^^^^^^^^^^^^^^^^^^
3508
3509 Syntax:
3510 """""""
3511
3512 ::
3513
3514       <result> = add <ty> <op1>, <op2>          ; yields {ty}:result
3515       <result> = add nuw <ty> <op1>, <op2>      ; yields {ty}:result
3516       <result> = add nsw <ty> <op1>, <op2>      ; yields {ty}:result
3517       <result> = add nuw nsw <ty> <op1>, <op2>  ; yields {ty}:result
3518
3519 Overview:
3520 """""""""
3521
3522 The '``add``' instruction returns the sum of its two operands.
3523
3524 Arguments:
3525 """"""""""
3526
3527 The two arguments to the '``add``' instruction must be
3528 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
3529 arguments must have identical types.
3530
3531 Semantics:
3532 """"""""""
3533
3534 The value produced is the integer sum of the two operands.
3535
3536 If the sum has unsigned overflow, the result returned is the
3537 mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
3538 the result.
3539
3540 Because LLVM integers use a two's complement representation, this
3541 instruction is appropriate for both signed and unsigned integers.
3542
3543 ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
3544 respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
3545 result value of the ``add`` is a :ref:`poison value <poisonvalues>` if
3546 unsigned and/or signed overflow, respectively, occurs.
3547
3548 Example:
3549 """"""""
3550
3551 .. code-block:: llvm
3552
3553       <result> = add i32 4, %var          ; yields {i32}:result = 4 + %var
3554
3555 .. _i_fadd:
3556
3557 '``fadd``' Instruction
3558 ^^^^^^^^^^^^^^^^^^^^^^
3559
3560 Syntax:
3561 """""""
3562
3563 ::
3564
3565       <result> = fadd [fast-math flags]* <ty> <op1>, <op2>   ; yields {ty}:result
3566
3567 Overview:
3568 """""""""
3569
3570 The '``fadd``' instruction returns the sum of its two operands.
3571
3572 Arguments:
3573 """"""""""
3574
3575 The two arguments to the '``fadd``' instruction must be :ref:`floating
3576 point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
3577 Both arguments must have identical types.
3578
3579 Semantics:
3580 """"""""""
3581
3582 The value produced is the floating point sum of the two operands. This
3583 instruction can also take any number of :ref:`fast-math flags <fastmath>`,
3584 which are optimization hints to enable otherwise unsafe floating point
3585 optimizations:
3586
3587 Example:
3588 """"""""
3589
3590 .. code-block:: llvm
3591
3592       <result> = fadd float 4.0, %var          ; yields {float}:result = 4.0 + %var
3593
3594 '``sub``' Instruction
3595 ^^^^^^^^^^^^^^^^^^^^^
3596
3597 Syntax:
3598 """""""
3599
3600 ::
3601
3602       <result> = sub <ty> <op1>, <op2>          ; yields {ty}:result
3603       <result> = sub nuw <ty> <op1>, <op2>      ; yields {ty}:result
3604       <result> = sub nsw <ty> <op1>, <op2>      ; yields {ty}:result
3605       <result> = sub nuw nsw <ty> <op1>, <op2>  ; yields {ty}:result
3606
3607 Overview:
3608 """""""""
3609
3610 The '``sub``' instruction returns the difference of its two operands.
3611
3612 Note that the '``sub``' instruction is used to represent the '``neg``'
3613 instruction present in most other intermediate representations.
3614
3615 Arguments:
3616 """"""""""
3617
3618 The two arguments to the '``sub``' instruction must be
3619 :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
3620 arguments must have identical types.
3621
3622 Semantics:
3623 """"""""""
3624
3625 The value produced is the integer difference of the two operands.
3626
3627 If the difference has unsigned overflow, the result returned is the
3628 mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
3629 the result.
3630
3631 Because LLVM integers use a two's complement representation, this
3632 instruction is appropriate for both signed and unsigned integers.
3633
3634 ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
3635 respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
3636 result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if
3637 unsigned and/or signed overflow, respectively, occurs.
3638
3639 Example:
3640 """"""""
3641
3642 .. code-block:: llvm
3643
3644       <result> = sub i32 4, %var          ; yields {i32}:result = 4 - %var
3645       <result> = sub i32 0, %val          ; yields {i32}:result = -%var
3646
3647 .. _i_fsub:
3648
3649 '``fsub``' Instruction
3650 ^^^^^^^^^^^^^^^^^^^^^^
3651
3652 Syntax:
3653 """""""
3654
3655 ::
3656
3657       <result> = fsub [fast-math flags]* <ty> <op1>, <op2>   ; yields {ty}:result
3658
3659 Overview:
3660 """""""""
3661
3662 The '``fsub``' instruction returns the difference of its two operands.
3663
3664 Note that the '``fsub``' instruction is used to represent the '``fneg``'
3665 instruction present in most other intermediate representations.
3666
3667 Arguments:
3668 """"""""""
3669
3670 The two arguments to the '``fsub``' instruction must be :ref:`floating
3671 point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
3672 Both arguments must have identical types.
3673
3674 Semantics:
3675 """"""""""
3676
3677 The valu