LangRef.rst

Poison value behavior is defined in terms of value *dependence*:

-  Values other than :ref:`phi <i_phi>` nodes depend on their operands.
-  :ref:`Phi <i_phi>` nodes depend on the operand corresponding to
   their dynamic predecessor basic block.
-  Function arguments depend on the corresponding actual argument values
   in the dynamic callers of their functions.
-  :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>`
   instructions that dynamically transfer control back to them.
-  :ref:`Invoke <i_invoke>` instructions depend on the
   :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing
   call instructions that dynamically transfer control back to them.
-  Non-volatile loads and stores depend on the most recent stores to all
   of the referenced memory addresses, following the order in the IR
   (including loads and stores implied by intrinsics such as
   :ref:`@llvm.memcpy <int_memcpy>`.)
-  An instruction with externally visible side effects depends on the
   most recent preceding instruction with externally visible side
   effects, following the order in the IR. (This includes :ref:`volatile
   operations <volatile>`.)
-  An instruction *control-depends* on a :ref:`terminator
   instruction <terminators>` if the terminator instruction has
   multiple successors and the instruction is always executed when
   control transfers to one of the successors, and may not be executed
   when control is transferred to another.
-  Additionally, an instruction also *control-depends* on a terminator
   instruction if the set of instructions it otherwise depends on would
   be different if the terminator had transferred control to a different
   successor.
-  Dependence is transitive.

Poison Values have the same behavior as :ref:`undef values <undefvalues>`,
with the additional affect that any instruction which has a *dependence*
on a poison value has undefined behavior.

Here are some examples:

.. code-block:: llvm

    entry:
      %poison = sub nuw i32 0, 1           ; Results in a poison value.
      %still_poison = and i32 %poison, 0   ; 0, but also poison.
      %poison_yet_again = getelementptr i32* @h, i32 %still_poison
      store i32 0, i32* %poison_yet_again  ; memory at @h[0] is poisoned

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

      store volatile i32 %poison, i32* @g  ; External observation; undefined behavior.

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

      %cmp = icmp slt i32 %poison, 0       ; Returns a poison value.
      br i1 %cmp, label %true, label %end  ; Branch to either destination.

    true:
      store volatile i32 0, i32* @g        ; This is control-dependent on %cmp, so
                                           ; it has undefined behavior.
      br label %end

    end:
      %p = phi i32 [ 0, %entry ], [ 1, %true ]
                                           ; Both edges into this PHI are
                                           ; control-dependent on %cmp, so this
                                           ; always results in a poison value.

      store volatile i32 0, i32* @g        ; This would depend on the store in %true
                                           ; if %cmp is true, or the store in %entry
                                           ; otherwise, so this is undefined behavior.

      br i1 %cmp, label %second_true, label %second_end
                                           ; The same branch again, but this time the
                                           ; true block doesn't have side effects.

    second_true:
      ; No side effects!
      ret void

    second_end:
      store volatile i32 0, i32* @g        ; This time, the instruction always depends
                                           ; on the store in %end. Also, it is
                                           ; control-equivalent to %end, so this is
                                           ; well-defined (ignoring earlier undefined
                                           ; behavior in this example).

.. _blockaddress:

Addresses of Basic Blocks
-------------------------

``blockaddress(@function, %block)``

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

This value only has defined behavior when used as an operand to the
':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons
against null. Pointer equality tests between labels addresses results in
undefined behavior --- though, again, comparison against null is ok, and
no label is equal to the null pointer. This may be passed around as an
opaque pointer sized value as long as the bits are not inspected. This
allows ``ptrtoint`` and arithmetic to be performed on these values so
long as the original value is reconstituted before the ``indirectbr``
instruction.

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

Constant Expressions
--------------------

Constant expressions are used to allow expressions involving other
constants to be used as constants. Constant expressions may be of any
:ref:`first class <t_firstclass>` type and may involve any LLVM operation
that does not have side effects (e.g. load and call are not supported).
The following is the syntax for constant expressions:

``trunc (CST to TYPE)``
    Truncate a constant to another type. The bit size of CST must be
    larger than the bit size of TYPE. Both types must be integers.
``zext (CST to TYPE)``
    Zero extend a constant to another type. The bit size of CST must be
    smaller than the bit size of TYPE. Both types must be integers.
``sext (CST to TYPE)``
    Sign extend a constant to another type. The bit size of CST must be
    smaller than the bit size of TYPE. Both types must be integers.
``fptrunc (CST to TYPE)``
    Truncate a floating point constant to another floating point type.
    The size of CST must be larger than the size of TYPE. Both types
    must be floating point.
``fpext (CST to TYPE)``
    Floating point extend a constant to another type. The size of CST
    must be smaller or equal to the size of TYPE. Both types must be
    floating point.
``fptoui (CST to TYPE)``
    Convert a floating point constant to the corresponding unsigned
    integer constant. TYPE must be a scalar or vector integer type. CST
    must be of scalar or vector floating point type. Both CST and TYPE
    must be scalars, or vectors of the same number of elements. If the
    value won't fit in the integer type, the results are undefined.
``fptosi (CST to TYPE)``
    Convert a floating point constant to the corresponding signed
    integer constant. TYPE must be a scalar or vector integer type. CST
    must be of scalar or vector floating point type. Both CST and TYPE
    must be scalars, or vectors of the same number of elements. If the
    value won't fit in the integer type, the results are undefined.
``uitofp (CST to TYPE)``
    Convert an unsigned integer constant to the corresponding floating
    point constant. TYPE must be a scalar or vector floating point type.
    CST must be of scalar or vector integer type. Both CST and TYPE must
    be scalars, or vectors of the same number of elements. If the value
    won't fit in the floating point type, the results are undefined.
``sitofp (CST to TYPE)``
    Convert a signed integer constant to the corresponding floating
    point constant. TYPE must be a scalar or vector floating point type.
    CST must be of scalar or vector integer type. Both CST and TYPE must
    be scalars, or vectors of the same number of elements. If the value
    won't fit in the floating point type, the results are undefined.
``ptrtoint (CST to TYPE)``
    Convert a pointer typed constant to the corresponding integer
    constant ``TYPE`` must be an integer type. ``CST`` must be of
    pointer type. The ``CST`` value is zero extended, truncated, or
    unchanged to make it fit in ``TYPE``.
``inttoptr (CST to TYPE)``
    Convert an integer constant to a pointer constant. TYPE must be a
    pointer type. CST must be of integer type. The CST value is zero
    extended, truncated, or unchanged to make it fit in a pointer size.
    This one is *really* dangerous!
``bitcast (CST to TYPE)``
    Convert a constant, CST, to another TYPE. The constraints of the
    operands are the same as those for the :ref:`bitcast
    instruction <i_bitcast>`.
``getelementptr (CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)``
    Perform the :ref:`getelementptr operation <i_getelementptr>` on
    constants. As with the :ref:`getelementptr <i_getelementptr>`
    instruction, the index list may have zero or more indexes, which are
    required to make sense for the type of "CSTPTR".
``select (COND, VAL1, VAL2)``
    Perform the :ref:`select operation <i_select>` on constants.
``icmp COND (VAL1, VAL2)``
    Performs the :ref:`icmp operation <i_icmp>` on constants.
``fcmp COND (VAL1, VAL2)``
    Performs the :ref:`fcmp operation <i_fcmp>` on constants.
``extractelement (VAL, IDX)``
    Perform the :ref:`extractelement operation <i_extractelement>` on
    constants.
``insertelement (VAL, ELT, IDX)``
    Perform the :ref:`insertelement operation <i_insertelement>` on
    constants.
``shufflevector (VEC1, VEC2, IDXMASK)``
    Perform the :ref:`shufflevector operation <i_shufflevector>` on
    constants.
``extractvalue (VAL, IDX0, IDX1, ...)``
    Perform the :ref:`extractvalue operation <i_extractvalue>` on
    constants. The index list is interpreted in a similar manner as
    indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At
    least one index value must be specified.
``insertvalue (VAL, ELT, IDX0, IDX1, ...)``
    Perform the :ref:`insertvalue operation <i_insertvalue>` on constants.
    The index list is interpreted in a similar manner as indices in a
    ':ref:`getelementptr <i_getelementptr>`' operation. At least one index
    value must be specified.
``OPCODE (LHS, RHS)``
    Perform the specified operation of the LHS and RHS constants. OPCODE
    may be any of the :ref:`binary <binaryops>` or :ref:`bitwise
    binary <bitwiseops>` operations. The constraints on operands are
    the same as those for the corresponding instruction (e.g. no bitwise
    operations on floating point values are allowed).

Other Values
============

Inline Assembler Expressions
----------------------------

LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level
Inline Assembly <moduleasm>`) through the use of a special value. This
value represents the inline assembler as a string (containing the
instructions to emit), a list of operand constraints (stored as a
string), a flag that indicates whether or not the inline asm expression
has side effects, and a flag indicating whether the function containing
the asm needs to align its stack conservatively. An example inline
assembler expression is:

.. code-block:: llvm

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

Inline assembler expressions may **only** be used as the callee operand
of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction.
Thus, typically we have:

.. code-block:: llvm

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

Inline asms with side effects not visible in the constraint list must be
marked as having side effects. This is done through the use of the
'``sideeffect``' keyword, like so:

.. code-block:: llvm

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

In some cases inline asms will contain code that will not work unless
the stack is aligned in some way, such as calls or SSE instructions on
x86, yet will not contain code that does that alignment within the asm.
The compiler should make conservative assumptions about what the asm
might contain and should generate its usual stack alignment code in the
prologue if the '``alignstack``' keyword is present:

.. code-block:: llvm

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

Inline asms also support using non-standard assembly dialects. The
assumed dialect is ATT. When the '``inteldialect``' keyword is present,
the inline asm is using the Intel dialect. Currently, ATT and Intel are
the only supported dialects. An example is:

.. code-block:: llvm

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

If multiple keywords appear the '``sideeffect``' keyword must come
first, the '``alignstack``' keyword second and the '``inteldialect``'
keyword last.

Inline Asm Metadata
^^^^^^^^^^^^^^^^^^^

The call instructions that wrap inline asm nodes may have a
"``!srcloc``" MDNode attached to it that contains a list of constant
integers. If present, the code generator will use the integer as the
location cookie value when report errors through the ``LLVMContext``
error reporting mechanisms. This allows a front-end to correlate backend
errors that occur with inline asm back to the source code that produced
it. For example:

.. code-block:: llvm

    call void asm sideeffect "something bad", ""(), !srcloc !42
    ...
    !42 = !{ i32 1234567 }

It is up to the front-end to make sense of the magic numbers it places
in the IR. If the MDNode contains multiple constants, the code generator
will use the one that corresponds to the line of the asm that the error
occurs on.

.. _metadata:

Metadata Nodes and Metadata Strings
-----------------------------------

LLVM IR allows metadata to be attached to instructions in the program
that can convey extra information about the code to the optimizers and
code generator. One example application of metadata is source-level
debug information. There are two metadata primitives: strings and nodes.
All metadata has the ``metadata`` type and is identified in syntax by a
preceding exclamation point ('``!``').

A metadata string is a string surrounded by double quotes. It can
contain any character by escaping non-printable characters with
"``\xx``" where "``xx``" is the two digit hex code. For example:
"``!"test\00"``".

Metadata nodes are represented with notation similar to structure
constants (a comma separated list of elements, surrounded by braces and
preceded by an exclamation point). Metadata nodes can have any values as
their operand. For example:

.. code-block:: llvm

    !{ metadata !"test\00", i32 10}

A :ref:`named metadata <namedmetadatastructure>` is a collection of
metadata nodes, which can be looked up in the module symbol table. For
example:

.. code-block:: llvm

    !foo =  metadata !{!4, !3}

Metadata can be used as function arguments. Here ``llvm.dbg.value``
function is using two metadata arguments:

.. code-block:: llvm

    call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)

Metadata can be attached with an instruction. Here metadata ``!21`` is
attached to the ``add`` instruction using the ``!dbg`` identifier:

.. code-block:: llvm

    %indvar.next = add i64 %indvar, 1, !dbg !21

More information about specific metadata nodes recognized by the
optimizers and code generator is found below.

'``tbaa``' Metadata
^^^^^^^^^^^^^^^^^^^

In LLVM IR, memory does not have types, so LLVM's own type system is not
suitable for doing TBAA. Instead, metadata is added to the IR to
describe a type system of a higher level language. This can be used to
implement typical C/C++ TBAA, but it can also be used to implement
custom alias analysis behavior for other languages.

The current metadata format is very simple. TBAA metadata nodes have up
to three fields, e.g.:

.. code-block:: llvm

    !0 = metadata !{ metadata !"an example type tree" }
    !1 = metadata !{ metadata !"int", metadata !0 }
    !2 = metadata !{ metadata !"float", metadata !0 }
    !3 = metadata !{ metadata !"const float", metadata !2, i64 1 }

The first field is an identity field. It can be any value, usually a
metadata string, which uniquely identifies the type. The most important
name in the tree is the name of the root node. Two trees with different
root node names are entirely disjoint, even if they have leaves with
common names.

The second field identifies the type's parent node in the tree, or is
null or omitted for a root node. A type is considered to alias all of
its descendants and all of its ancestors in the tree. Also, a type is
considered to alias all types in other trees, so that bitcode produced
from multiple front-ends is handled conservatively.

If the third field is present, it's an integer which if equal to 1
indicates that the type is "constant" (meaning
``pointsToConstantMemory`` should return true; see `other useful
AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_).

'``tbaa.struct``' Metadata
^^^^^^^^^^^^^^^^^^^^^^^^^^

The :ref:`llvm.memcpy <int_memcpy>` is often used to implement
aggregate assignment operations in C and similar languages, however it
is defined to copy a contiguous region of memory, which is more than
strictly necessary for aggregate types which contain holes due to
padding. Also, it doesn't contain any TBAA information about the fields
of the aggregate.

``!tbaa.struct`` metadata can describe which memory subregions in a
memcpy are padding and what the TBAA tags of the struct are.

The current metadata format is very simple. ``!tbaa.struct`` metadata
nodes are a list of operands which are in conceptual groups of three.
For each group of three, the first operand gives the byte offset of a
field in bytes, the second gives its size in bytes, and the third gives
its tbaa tag. e.g.:

.. code-block:: llvm

    !4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }

This describes a struct with two fields. The first is at offset 0 bytes
with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
and has size 4 bytes and has tbaa tag !2.

Note that the fields need not be contiguous. In this example, there is a
4 byte gap between the two fields. This gap represents padding which
does not carry useful data and need not be preserved.

'``fpmath``' Metadata
^^^^^^^^^^^^^^^^^^^^^

``fpmath`` metadata may be attached to any instruction of floating point
type. It can be used to express the maximum acceptable error in the
result of that instruction, in ULPs, thus potentially allowing the
compiler to use a more efficient but less accurate method of computing
it. ULP is defined as follows:

    If ``x`` is a real number that lies between two finite consecutive
    floating-point numbers ``a`` and ``b``, without being equal to one
    of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the
    distance between the two non-equal finite floating-point numbers
    nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``.

The metadata node shall consist of a single positive floating point
number representing the maximum relative error, for example:

.. code-block:: llvm

    !0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs

'``range``' Metadata
^^^^^^^^^^^^^^^^^^^^

``range`` metadata may be attached only to loads of integer types. It
expresses the possible ranges the loaded value is in. The ranges are
represented with a flattened list of integers. The loaded value is known
to be in the union of the ranges defined by each consecutive pair. Each
pair has the following properties:

-  The type must match the type loaded by the instruction.
-  The pair ``a,b`` represents the range ``[a,b)``.
-  Both ``a`` and ``b`` are constants.
-  The range is allowed to wrap.
-  The range should not represent the full or empty set. That is,
   ``a!=b``.

In addition, the pairs must be in signed order of the lower bound and
they must be non-contiguous.

Examples:

.. code-block:: llvm

      %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
      %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
      %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
      %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5
    ...
    !0 = metadata !{ i8 0, i8 2 }
    !1 = metadata !{ i8 255, i8 2 }
    !2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
    !3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }

Module Flags Metadata
=====================

Information about the module as a whole is difficult to convey to LLVM's
subsystems. The LLVM IR isn't sufficient to transmit this information.
The ``llvm.module.flags`` named metadata exists in order to facilitate
this. These flags are in the form of key / value pairs --- much like a
dictionary --- making it easy for any subsystem who cares about a flag to
look it up.

The ``llvm.module.flags`` metadata contains a list of metadata triplets.
Each triplet has the following form:

-  The first element is a *behavior* flag, which specifies the behavior
   when two (or more) modules are merged together, and it encounters two
   (or more) metadata with the same ID. The supported behaviors are
   described below.
-  The second element is a metadata string that is a unique ID for the
   metadata. Each module may only have one flag entry for each unique ID (not
   including entries with the **Require** behavior).
-  The third element is the value of the flag.

When two (or more) modules are merged together, the resulting
``llvm.module.flags`` metadata is the union of the modules' flags. That is, for
each unique metadata ID string, there will be exactly one entry in the merged
modules ``llvm.module.flags`` metadata table, and the value for that entry will
be determined by the merge behavior flag, as described below. The only exception
is that entries with the *Require* behavior are always preserved.

The following behaviors are supported:

.. list-table::
   :header-rows: 1
   :widths: 10 90

   * - Value
     - Behavior

   * - 1
     - **Error**
           Emits an error if two values disagree, otherwise the resulting value
           is that of the operands.

   * - 2
     - **Warning**
           Emits a warning if two values disagree. The result value will be the
           operand for the flag from the first module being linked.

   * - 3
     - **Require**
           Adds a requirement that another module flag be present and have a
           specified value after linking is performed. The value must be a
           metadata pair, where the first element of the pair is the ID of the
           module flag to be restricted, and the second element of the pair is
           the value the module flag should be restricted to. This behavior can
           be used to restrict the allowable results (via triggering of an
           error) of linking IDs with the **Override** behavior.

   * - 4
     - **Override**
           Uses the specified value, regardless of the behavior or value of the
           other module. If both modules specify **Override**, but the values
           differ, an error will be emitted.

   * - 5
     - **Append**
           Appends the two values, which are required to be metadata nodes.

   * - 6
     - **AppendUnique**
           Appends the two values, which are required to be metadata
           nodes. However, duplicate entries in the second list are dropped
           during the append operation.

It is an error for a particular unique flag ID to have multiple behaviors,
except in the case of **Require** (which adds restrictions on another metadata
value) or **Override**.

An example of module flags:

.. code-block:: llvm

    !0 = metadata !{ i32 1, metadata !"foo", i32 1 }
    !1 = metadata !{ i32 4, metadata !"bar", i32 37 }
    !2 = metadata !{ i32 2, metadata !"qux", i32 42 }
    !3 = metadata !{ i32 3, metadata !"qux",
      metadata !{
        metadata !"foo", i32 1
      }
    }
    !llvm.module.flags = !{ !0, !1, !2, !3 }

-  Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior
   if two or more ``!"foo"`` flags are seen is to emit an error if their
   values are not equal.

-  Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The
   behavior if two or more ``!"bar"`` flags are seen is to use the value
   '37'.

-  Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The
   behavior if two or more ``!"qux"`` flags are seen is to emit a
   warning if their values are not equal.

-  Metadata ``!3`` has the ID ``!"qux"`` and the value:

   ::

       metadata !{ metadata !"foo", i32 1 }

   The behavior is to emit an error if the ``llvm.module.flags`` does not
   contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
   performed.

Objective-C Garbage Collection Module Flags Metadata
----------------------------------------------------

On the Mach-O platform, Objective-C stores metadata about garbage
collection in a special section called "image info". The metadata
consists of a version number and a bitmask specifying what types of
garbage collection are supported (if any) by the file. If two or more
modules are linked together their garbage collection metadata needs to
be merged rather than appended together.

The Objective-C garbage collection module flags metadata consists of the
following key-value pairs:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Key
     - Value

   * - ``Objective-C Version``
     - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2.

   * - ``Objective-C Image Info Version``
     - **[Required]** --- The version of the image info section. Currently
       always 0.

   * - ``Objective-C Image Info Section``
     - **[Required]** --- The section to place the metadata. Valid values are
       ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and
       ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for
       Objective-C ABI version 2.

   * - ``Objective-C Garbage Collection``
     - **[Required]** --- Specifies whether garbage collection is supported or
       not. Valid values are 0, for no garbage collection, and 2, for garbage
       collection supported.

   * - ``Objective-C GC Only``
     - **[Optional]** --- Specifies that only garbage collection is supported.
       If present, its value must be 6. This flag requires that the
       ``Objective-C Garbage Collection`` flag have the value 2.

Some important flag interactions:

-  If a module with ``Objective-C Garbage Collection`` set to 0 is
   merged with a module with ``Objective-C Garbage Collection`` set to
   2, then the resulting module has the
   ``Objective-C Garbage Collection`` flag set to 0.
-  A module with ``Objective-C Garbage Collection`` set to 0 cannot be
   merged with a module with ``Objective-C GC Only`` set to 6.

Automatic Linker Flags Module Flags Metadata
--------------------------------------------

Some targets support embedding flags to the linker inside individual object
files. Typically this is used in conjunction with language extensions which
allow source files to explicitly declare the libraries they depend on, and have
these automatically be transmitted to the linker via object files.

These flags are encoded in the IR using metadata in the module flags section,
using the ``Linker Options`` key. The merge behavior for this flag is required
to be ``AppendUnique``, and the value for the key is expected to be a metadata
node which should be a list of other metadata nodes, each of which should be a
list of metadata strings defining linker options.

For example, the following metadata section specifies two separate sets of
linker options, presumably to link against ``libz`` and the ``Cocoa``
framework::

    !0 = metadata !{ i32 6, metadata !"Linker Options", 
       metadata !{
          metadata !{ metadata !"-lz" },
          metadata !{ metadata !"-framework", metadata !"Cocoa" } } }
    !llvm.module.flags = !{ !0 }

The metadata encoding as lists of lists of options, as opposed to a collapsed
list of options, is chosen so that the IR encoding can use multiple option
strings to specify e.g., a single library, while still having that specifier be
preserved as an atomic element that can be recognized by a target specific
assembly writer or object file emitter.

Each individual option is required to be either a valid option for the target's
linker, or an option that is reserved by the target specific assembly writer or
object file emitter. No other aspect of these options is defined by the IR.

Intrinsic Global Variables
==========================

LLVM has a number of "magic" global variables that contain data that
affect code generation or other IR semantics. These are documented here.
All globals of this sort should have a section specified as
"``llvm.metadata``". This section and all globals that start with
"``llvm.``" are reserved for use by LLVM.

The '``llvm.used``' Global Variable
-----------------------------------

The ``@llvm.used`` global is an array with i8\* element type which has
:ref:`appending linkage <linkage_appending>`. This array contains a list of
pointers to global variables and functions which may optionally have a
pointer cast formed of bitcast or getelementptr. For example, a legal
use of it is:

.. code-block:: llvm

    @X = global i8 4
    @Y = global i32 123

    @llvm.used = appending global [2 x i8*] [
       i8* @X,
       i8* bitcast (i32* @Y to i8*)
    ], section "llvm.metadata"

If a global variable appears in the ``@llvm.used`` list, then the
compiler, assembler, and linker are required to treat the symbol as if
there is a reference to the global that it cannot see. For example, if a
variable has internal linkage and no references other than that from the
``@llvm.used`` list, it cannot be deleted. This is commonly used to
represent references from inline asms and other things the compiler
cannot "see", and corresponds to "``attribute((used))``" in GNU C.

On some targets, the code generator must emit a directive to the
assembler or object file to prevent the assembler and linker from
molesting the symbol.

The '``llvm.compiler.used``' Global Variable
--------------------------------------------

The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used``
directive, except that it only prevents the compiler from touching the
symbol. On targets that support it, this allows an intelligent linker to
optimize references to the symbol without being impeded as it would be
by ``@llvm.used``.

This is a rare construct that should only be used in rare circumstances,
and should not be exposed to source languages.

The '``llvm.global_ctors``' Global Variable
-------------------------------------------

.. code-block:: llvm

    %0 = type { i32, void ()* }
    @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]

The ``@llvm.global_ctors`` array contains a list of constructor
functions and associated priorities. The functions referenced by this
array will be called in ascending order of priority (i.e. lowest first)
when the module is loaded. The order of functions with the same priority
is not defined.

The '``llvm.global_dtors``' Global Variable
-------------------------------------------

.. code-block:: llvm

    %0 = type { i32, void ()* }
    @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]

The ``@llvm.global_dtors`` array contains a list of destructor functions
and associated priorities. The functions referenced by this array will
be called in descending order of priority (i.e. highest first) when the
module is loaded. The order of functions with the same priority is not
defined.

Instruction Reference
=====================

The LLVM instruction set consists of several different classifications
of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
instructions <binaryops>`, :ref:`bitwise binary
instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
:ref:`other instructions <otherops>`.

.. _terminators:

Terminator Instructions
-----------------------

As mentioned :ref:`previously <functionstructure>`, every basic block in a
program ends with a "Terminator" instruction, which indicates which
block should be executed after the current block is finished. These
terminator instructions typically yield a '``void``' value: they produce
control flow, not values (the one exception being the
':ref:`invoke <i_invoke>`' instruction).

The terminator instructions are: ':ref:`ret <i_ret>`',
':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
':ref:`resume <i_resume>`', and ':ref:`unreachable <i_unreachable>`'.

.. _i_ret:

'``ret``' Instruction
^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      ret <type> <value>       ; Return a value from a non-void function
      ret void                 ; Return from void function

Overview:
"""""""""

The '``ret``' instruction is used to return control flow (and optionally
a value) from a function back to the caller.

There are two forms of the '``ret``' instruction: one that returns a
value and then causes control flow, and one that just causes control
flow to occur.

Arguments:
""""""""""

The '``ret``' instruction optionally accepts a single argument, the
return value. The type of the return value must be a ':ref:`first
class <t_firstclass>`' type.

A function is not :ref:`well formed <wellformed>` if it it has a non-void
return type and contains a '``ret``' instruction with no return value or
a return value with a type that does not match its type, or if it has a
void return type and contains a '``ret``' instruction with a return
value.

Semantics:
""""""""""

When the '``ret``' instruction is executed, control flow returns back to
the calling function's context. If the caller is a
":ref:`call <i_call>`" instruction, execution continues at the
instruction after the call. If the caller was an
":ref:`invoke <i_invoke>`" instruction, execution continues at the
beginning of the "normal" destination block. If the instruction returns
a value, that value shall set the call or invoke instruction's return
value.

Example:
""""""""

.. code-block:: llvm

      ret i32 5                       ; Return an integer value of 5
      ret void                        ; Return from a void function
      ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2

.. _i_br:

'``br``' Instruction
^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      br i1 <cond>, label <iftrue>, label <iffalse>
      br label <dest>          ; Unconditional branch

Overview:
"""""""""

The '``br``' instruction is used to cause control flow to transfer to a
different basic block in the current function. There are two forms of
this instruction, corresponding to a conditional branch and an
unconditional branch.

Arguments:
""""""""""

The conditional branch form of the '``br``' instruction takes a single
'``i1``' value and two '``label``' values. The unconditional form of the
'``br``' instruction takes a single '``label``' value as a target.

Semantics:
""""""""""

Upon execution of a conditional '``br``' instruction, the '``i1``'
argument is evaluated. If the value is ``true``, control flows to the
'``iftrue``' ``label`` argument. If "cond" is ``false``, control flows
to the '``iffalse``' ``label`` argument.

Example:
""""""""

.. code-block:: llvm

    Test:
      %cond = icmp eq i32 %a, %b
      br i1 %cond, label %IfEqual, label %IfUnequal
    IfEqual:
      ret i32 1
    IfUnequal:
      ret i32 0

.. _i_switch:

'``switch``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]

Overview:
"""""""""

The '``switch``' instruction is used to transfer control flow to one of
several different places. It is a generalization of the '``br``'
instruction, allowing a branch to occur to one of many possible
destinations.

Arguments:
""""""""""

The '``switch``' instruction uses three parameters: an integer
comparison value '``value``', a default '``label``' destination, and an
array of pairs of comparison value constants and '``label``'s. The table
is not allowed to contain duplicate constant entries.

Semantics:
""""""""""

The ``switch`` instruction specifies a table of values and destinations.
When the '``switch``' instruction is executed, this table is searched
for the given value. If the value is found, control flow is transferred
to the corresponding destination; otherwise, control flow is transferred
to the default destination.

Implementation:
"""""""""""""""

Depending on properties of the target machine and the particular
``switch`` instruction, this instruction may be code generated in
different ways. For example, it could be generated as a series of
chained conditional branches or with a lookup table.

Example:
""""""""

.. code-block:: llvm

     ; Emulate a conditional br instruction
     %Val = zext i1 %value to i32
     switch i32 %Val, label %truedest [ i32 0, label %falsedest ]

     ; Emulate an unconditional br instruction
     switch i32 0, label %dest [ ]

     ; Implement a jump table:
     switch i32 %val, label %otherwise [ i32 0, label %onzero
                                         i32 1, label %onone
                                         i32 2, label %ontwo ]

.. _i_indirectbr:

'``indirectbr``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]

Overview:
"""""""""

The '``indirectbr``' instruction implements an indirect branch to a
label within the current function, whose address is specified by
"``address``". Address must be derived from a
:ref:`blockaddress <blockaddress>` constant.

Arguments:
""""""""""

The '``address``' argument is the address of the label to jump to. The
rest of the arguments indicate the full set of possible destinations
that the address may point to. Blocks are allowed to occur multiple
times in the destination list, though this isn't particularly useful.

This destination list is required so that dataflow analysis has an
accurate understanding of the CFG.

Semantics:
""""""""""

Control transfers to the block specified in the address argument. All
possible destination blocks must be listed in the label list, otherwise
this instruction has undefined behavior. This implies that jumps to
labels defined in other functions have undefined behavior as well.

Implementation:
"""""""""""""""

This is typically implemented with a jump through a register.

Example:
""""""""

.. code-block:: llvm

     indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]

.. _i_invoke:

'``invoke``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""