LangRef.rst

The '``fptrunc``' instruction takes a :ref:`floating point <t_floating>`
value to cast and a :ref:`floating point <t_floating>` type to cast it to.
The size of ``value`` must be larger than the size of ``ty2``. This
implies that ``fptrunc`` cannot be used to make a *no-op cast*.

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

The '``fptrunc``' instruction truncates a ``value`` from a larger
:ref:`floating point <t_floating>` type to a smaller :ref:`floating
point <t_floating>` type. If the value cannot fit within the
destination type, ``ty2``, then the results are undefined.

Example:
""""""""

.. code-block:: llvm

      %X = fptrunc double 123.0 to float         ; yields float:123.0
      %Y = fptrunc double 1.0E+300 to float      ; yields undefined

'``fpext .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = fpext <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``fpext``' extends a floating point ``value`` to a larger floating
point value.

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

The '``fpext``' instruction takes a :ref:`floating point <t_floating>`
``value`` to cast, and a :ref:`floating point <t_floating>` type to cast it
to. The source type must be smaller than the destination type.

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

The '``fpext``' instruction extends the ``value`` from a smaller
:ref:`floating point <t_floating>` type to a larger :ref:`floating
point <t_floating>` type. The ``fpext`` cannot be used to make a
*no-op cast* because it always changes bits. Use ``bitcast`` to make a
*no-op cast* for a floating point cast.

Example:
""""""""

.. code-block:: llvm

      %X = fpext float 3.125 to double         ; yields double:3.125000e+00
      %Y = fpext double %X to fp128            ; yields fp128:0xL00000000000000004000900000000000

'``fptoui .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = fptoui <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``fptoui``' converts a floating point ``value`` to its unsigned
integer equivalent of type ``ty2``.

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

The '``fptoui``' instruction takes a value to cast, which must be a
scalar or vector :ref:`floating point <t_floating>` value, and a type to
cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
``ty`` is a vector floating point type, ``ty2`` must be a vector integer
type with the same number of elements as ``ty``

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

The '``fptoui``' instruction converts its :ref:`floating
point <t_floating>` operand into the nearest (rounding towards zero)
unsigned integer value. If the value cannot fit in ``ty2``, the results
are undefined.

Example:
""""""""

.. code-block:: llvm

      %X = fptoui double 123.0 to i32      ; yields i32:123
      %Y = fptoui float 1.0E+300 to i1     ; yields undefined:1
      %Z = fptoui float 1.04E+17 to i8     ; yields undefined:1

'``fptosi .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = fptosi <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``fptosi``' instruction converts :ref:`floating point <t_floating>`
``value`` to type ``ty2``.

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

The '``fptosi``' instruction takes a value to cast, which must be a
scalar or vector :ref:`floating point <t_floating>` value, and a type to
cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
``ty`` is a vector floating point type, ``ty2`` must be a vector integer
type with the same number of elements as ``ty``

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

The '``fptosi``' instruction converts its :ref:`floating
point <t_floating>` operand into the nearest (rounding towards zero)
signed integer value. If the value cannot fit in ``ty2``, the results
are undefined.

Example:
""""""""

.. code-block:: llvm

      %X = fptosi double -123.0 to i32      ; yields i32:-123
      %Y = fptosi float 1.0E-247 to i1      ; yields undefined:1
      %Z = fptosi float 1.04E+17 to i8      ; yields undefined:1

'``uitofp .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = uitofp <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``uitofp``' instruction regards ``value`` as an unsigned integer
and converts that value to the ``ty2`` type.

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

The '``uitofp``' instruction takes a value to cast, which must be a
scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
``ty2``, which must be an :ref:`floating point <t_floating>` type. If
``ty`` is a vector integer type, ``ty2`` must be a vector floating point
type with the same number of elements as ``ty``

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

The '``uitofp``' instruction interprets its operand as an unsigned
integer quantity and converts it to the corresponding floating point
value. If the value cannot fit in the floating point value, the results
are undefined.

Example:
""""""""

.. code-block:: llvm

      %X = uitofp i32 257 to float         ; yields float:257.0
      %Y = uitofp i8 -1 to double          ; yields double:255.0

'``sitofp .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = sitofp <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``sitofp``' instruction regards ``value`` as a signed integer and
converts that value to the ``ty2`` type.

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

The '``sitofp``' instruction takes a value to cast, which must be a
scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
``ty2``, which must be an :ref:`floating point <t_floating>` type. If
``ty`` is a vector integer type, ``ty2`` must be a vector floating point
type with the same number of elements as ``ty``

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

The '``sitofp``' instruction interprets its operand as a signed integer
quantity and converts it to the corresponding floating point value. If
the value cannot fit in the floating point value, the results are
undefined.

Example:
""""""""

.. code-block:: llvm

      %X = sitofp i32 257 to float         ; yields float:257.0
      %Y = sitofp i8 -1 to double          ; yields double:-1.0

.. _i_ptrtoint:

'``ptrtoint .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = ptrtoint <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``ptrtoint``' instruction converts the pointer or a vector of
pointers ``value`` to the integer (or vector of integers) type ``ty2``.

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

The '``ptrtoint``' instruction takes a ``value`` to cast, which must be
a a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a
type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or
a vector of integers type.

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

The '``ptrtoint``' instruction converts ``value`` to integer type
``ty2`` by interpreting the pointer value as an integer and either
truncating or zero extending that value to the size of the integer type.
If ``value`` is smaller than ``ty2`` then a zero extension is done. If
``value`` is larger than ``ty2`` then a truncation is done. If they are
the same size, then nothing is done (*no-op cast*) other than a type
change.

Example:
""""""""

.. code-block:: llvm

      %X = ptrtoint i32* %P to i8                         ; yields truncation on 32-bit architecture
      %Y = ptrtoint i32* %P to i64                        ; yields zero extension on 32-bit architecture
      %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture

.. _i_inttoptr:

'``inttoptr .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = inttoptr <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``inttoptr``' instruction converts an integer ``value`` to a
pointer type, ``ty2``.

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

The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to
cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>`
type.

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

The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by
applying either a zero extension or a truncation depending on the size
of the integer ``value``. If ``value`` is larger than the size of a
pointer then a truncation is done. If ``value`` is smaller than the size
of a pointer then a zero extension is done. If they are the same size,
nothing is done (*no-op cast*).

Example:
""""""""

.. code-block:: llvm

      %X = inttoptr i32 255 to i32*          ; yields zero extension on 64-bit architecture
      %Y = inttoptr i32 255 to i32*          ; yields no-op on 32-bit architecture
      %Z = inttoptr i64 0 to i32*            ; yields truncation on 32-bit architecture
      %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers

.. _i_bitcast:

'``bitcast .. to``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = bitcast <ty> <value> to <ty2>             ; yields ty2

Overview:
"""""""""

The '``bitcast``' instruction converts ``value`` to type ``ty2`` without
changing any bits.

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

The '``bitcast``' instruction takes a value to cast, which must be a
non-aggregate first class value, and a type to cast it to, which must
also be a non-aggregate :ref:`first class <t_firstclass>` type. The bit
sizes of ``value`` and the destination type, ``ty2``, must be identical.
If the source type is a pointer, the destination type must also be a
pointer. This instruction supports bitwise conversion of vectors to
integers and to vectors of other types (as long as they have the same
size).

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

The '``bitcast``' instruction converts ``value`` to type ``ty2``. It is
always a *no-op cast* because no bits change with this conversion. The
conversion is done as if the ``value`` had been stored to memory and
read back as type ``ty2``. Pointer (or vector of pointers) types may
only be converted to other pointer (or vector of pointers) types with
this instruction. To convert pointers to other types, use the
:ref:`inttoptr <i_inttoptr>` or :ref:`ptrtoint <i_ptrtoint>` instructions
first.

Example:
""""""""

.. code-block:: llvm

      %X = bitcast i8 255 to i8              ; yields i8 :-1
      %Y = bitcast i32* %x to sint*          ; yields sint*:%x
      %Z = bitcast <2 x int> %V to i64;        ; yields i64: %V
      %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>

.. _otherops:

Other Operations
----------------

The instructions in this category are the "miscellaneous" instructions,
which defy better classification.

.. _i_icmp:

'``icmp``' Instruction
^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = icmp <cond> <ty> <op1>, <op2>   ; yields {i1} or {<N x i1>}:result

Overview:
"""""""""

The '``icmp``' instruction returns a boolean value or a vector of
boolean values based on comparison of its two integer, integer vector,
pointer, or pointer vector operands.

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

The '``icmp``' instruction takes three operands. The first operand is
the condition code indicating the kind of comparison to perform. It is
not a value, just a keyword. The possible condition code are:

#. ``eq``: equal
#. ``ne``: not equal
#. ``ugt``: unsigned greater than
#. ``uge``: unsigned greater or equal
#. ``ult``: unsigned less than
#. ``ule``: unsigned less or equal
#. ``sgt``: signed greater than
#. ``sge``: signed greater or equal
#. ``slt``: signed less than
#. ``sle``: signed less or equal

The remaining two arguments must be :ref:`integer <t_integer>` or
:ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They
must also be identical types.

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

The '``icmp``' compares ``op1`` and ``op2`` according to the condition
code given as ``cond``. The comparison performed always yields either an
:ref:`i1 <t_integer>` or vector of ``i1`` result, as follows:

#. ``eq``: yields ``true`` if the operands are equal, ``false``
   otherwise. No sign interpretation is necessary or performed.
#. ``ne``: yields ``true`` if the operands are unequal, ``false``
   otherwise. No sign interpretation is necessary or performed.
#. ``ugt``: interprets the operands as unsigned values and yields
   ``true`` if ``op1`` is greater than ``op2``.
#. ``uge``: interprets the operands as unsigned values and yields
   ``true`` if ``op1`` is greater than or equal to ``op2``.
#. ``ult``: interprets the operands as unsigned values and yields
   ``true`` if ``op1`` is less than ``op2``.
#. ``ule``: interprets the operands as unsigned values and yields
   ``true`` if ``op1`` is less than or equal to ``op2``.
#. ``sgt``: interprets the operands as signed values and yields ``true``
   if ``op1`` is greater than ``op2``.
#. ``sge``: interprets the operands as signed values and yields ``true``
   if ``op1`` is greater than or equal to ``op2``.
#. ``slt``: interprets the operands as signed values and yields ``true``
   if ``op1`` is less than ``op2``.
#. ``sle``: interprets the operands as signed values and yields ``true``
   if ``op1`` is less than or equal to ``op2``.

If the operands are :ref:`pointer <t_pointer>` typed, the pointer values
are compared as if they were integers.

If the operands are integer vectors, then they are compared element by
element. The result is an ``i1`` vector with the same number of elements
as the values being compared. Otherwise, the result is an ``i1``.

Example:
""""""""

.. code-block:: llvm

      <result> = icmp eq i32 4, 5          ; yields: result=false
      <result> = icmp ne float* %X, %X     ; yields: result=false
      <result> = icmp ult i16  4, 5        ; yields: result=true
      <result> = icmp sgt i16  4, 5        ; yields: result=false
      <result> = icmp ule i16 -4, 5        ; yields: result=false
      <result> = icmp sge i16  4, 5        ; yields: result=false

Note that the code generator does not yet support vector types with the
``icmp`` instruction.

.. _i_fcmp:

'``fcmp``' Instruction
^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = fcmp <cond> <ty> <op1>, <op2>     ; yields {i1} or {<N x i1>}:result

Overview:
"""""""""

The '``fcmp``' instruction returns a boolean value or vector of boolean
values based on comparison of its operands.

If the operands are floating point scalars, then the result type is a
boolean (:ref:`i1 <t_integer>`).

If the operands are floating point vectors, then the result type is a
vector of boolean with the same number of elements as the operands being
compared.

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

The '``fcmp``' instruction takes three operands. The first operand is
the condition code indicating the kind of comparison to perform. It is
not a value, just a keyword. The possible condition code are:

#. ``false``: no comparison, always returns false
#. ``oeq``: ordered and equal
#. ``ogt``: ordered and greater than
#. ``oge``: ordered and greater than or equal
#. ``olt``: ordered and less than
#. ``ole``: ordered and less than or equal
#. ``one``: ordered and not equal
#. ``ord``: ordered (no nans)
#. ``ueq``: unordered or equal
#. ``ugt``: unordered or greater than
#. ``uge``: unordered or greater than or equal
#. ``ult``: unordered or less than
#. ``ule``: unordered or less than or equal
#. ``une``: unordered or not equal
#. ``uno``: unordered (either nans)
#. ``true``: no comparison, always returns true

*Ordered* means that neither operand is a QNAN while *unordered* means
that either operand may be a QNAN.

Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating
point <t_floating>` type or a :ref:`vector <t_vector>` of floating point
type. They must have identical types.

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

The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the
condition code given as ``cond``. If the operands are vectors, then the
vectors are compared element by element. Each comparison performed
always yields an :ref:`i1 <t_integer>` result, as follows:

#. ``false``: always yields ``false``, regardless of operands.
#. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1``
   is equal to ``op2``.
#. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1``
   is greater than ``op2``.
#. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1``
   is greater than or equal to ``op2``.
#. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1``
   is less than ``op2``.
#. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1``
   is less than or equal to ``op2``.
#. ``one``: yields ``true`` if both operands are not a QNAN and ``op1``
   is not equal to ``op2``.
#. ``ord``: yields ``true`` if both operands are not a QNAN.
#. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is
   equal to ``op2``.
#. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is
   greater than ``op2``.
#. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is
   greater than or equal to ``op2``.
#. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is
   less than ``op2``.
#. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is
   less than or equal to ``op2``.
#. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is
   not equal to ``op2``.
#. ``uno``: yields ``true`` if either operand is a QNAN.
#. ``true``: always yields ``true``, regardless of operands.

Example:
""""""""

.. code-block:: llvm

      <result> = fcmp oeq float 4.0, 5.0    ; yields: result=false
      <result> = fcmp one float 4.0, 5.0    ; yields: result=true
      <result> = fcmp olt float 4.0, 5.0    ; yields: result=true
      <result> = fcmp ueq double 1.0, 2.0   ; yields: result=false

Note that the code generator does not yet support vector types with the
``fcmp`` instruction.

.. _i_phi:

'``phi``' Instruction
^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = phi <ty> [ <val0>, <label0>], ...

Overview:
"""""""""

The '``phi``' instruction is used to implement the φ node in the SSA
graph representing the function.

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

The type of the incoming values is specified with the first type field.
After this, the '``phi``' instruction takes a list of pairs as
arguments, with one pair for each predecessor basic block of the current
block. Only values of :ref:`first class <t_firstclass>` type may be used as
the value arguments to the PHI node. Only labels may be used as the
label arguments.

There must be no non-phi instructions between the start of a basic block
and the PHI instructions: i.e. PHI instructions must be first in a basic
block.

For the purposes of the SSA form, the use of each incoming value is
deemed to occur on the edge from the corresponding predecessor block to
the current block (but after any definition of an '``invoke``'
instruction's return value on the same edge).

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

At runtime, the '``phi``' instruction logically takes on the value
specified by the pair corresponding to the predecessor basic block that
executed just prior to the current block.

Example:
""""""""

.. code-block:: llvm

    Loop:       ; Infinite loop that counts from 0 on up...
      %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
      %nextindvar = add i32 %indvar, 1
      br label %Loop

.. _i_select:

'``select``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = select selty <cond>, <ty> <val1>, <ty> <val2>             ; yields ty

      selty is either i1 or {<N x i1>}

Overview:
"""""""""

The '``select``' instruction is used to choose one value based on a
condition, without branching.

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

The '``select``' instruction requires an 'i1' value or a vector of 'i1'
values indicating the condition, and two values of the same :ref:`first
class <t_firstclass>` type. If the val1/val2 are vectors and the
condition is a scalar, then entire vectors are selected, not individual
elements.

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

If the condition is an i1 and it evaluates to 1, the instruction returns
the first value argument; otherwise, it returns the second value
argument.

If the condition is a vector of i1, then the value arguments must be
vectors of the same size, and the selection is done element by element.

Example:
""""""""

.. code-block:: llvm

      %X = select i1 true, i8 17, i8 42          ; yields i8:17

.. _i_call:

'``call``' Instruction
^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <result> = [tail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]

Overview:
"""""""""

The '``call``' instruction represents a simple function call.

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

This instruction requires several arguments:

#. The optional "tail" marker indicates that the callee function does
   not access any allocas or varargs in the caller. Note that calls may
   be marked "tail" even if they do not occur before a
   :ref:`ret <i_ret>` instruction. If the "tail" marker is present, the
   function call is eligible for tail call optimization, but `might not
   in fact be optimized into a jump <CodeGenerator.html#tailcallopt>`_.
   The code generator may optimize calls marked "tail" with either 1)
   automatic `sibling call
   optimization <CodeGenerator.html#sibcallopt>`_ when the caller and
   callee have matching signatures, or 2) forced tail call optimization
   when the following extra requirements are met:

   -  Caller and callee both have the calling convention ``fastcc``.
   -  The call is in tail position (ret immediately follows call and ret
      uses value of call or is void).
   -  Option ``-tailcallopt`` is enabled, or
      ``llvm::GuaranteedTailCallOpt`` is ``true``.
   -  `Platform specific constraints are
      met. <CodeGenerator.html#tailcallopt>`_

#. The optional "cconv" marker indicates which :ref:`calling
   convention <callingconv>` the call should use. If none is
   specified, the call defaults to using C calling conventions. The
   calling convention of the call must match the calling convention of
   the target function, or else the behavior is undefined.
#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
   values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
   are valid here.
#. '``ty``': the type of the call instruction itself which is also the
   type of the return value. Functions that return no value are marked
   ``void``.
#. '``fnty``': shall be the signature of the pointer to function value
   being invoked. The argument types must match the types implied by
   this signature. This type can be omitted if the function is not
   varargs and if the function type does not return a pointer to a
   function.
#. '``fnptrval``': An LLVM value containing a pointer to a function to
   be invoked. In most cases, this is a direct function invocation, but
   indirect ``call``'s are just as possible, calling an arbitrary pointer
   to function value.
#. '``function args``': argument list whose types match the function
   signature argument types and parameter attributes. All arguments must
   be of :ref:`first class <t_firstclass>` type. If the function signature
   indicates the function accepts a variable number of arguments, the
   extra arguments can be specified.
#. The optional :ref:`function attributes <fnattrs>` list. Only
   '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
   attributes are valid here.

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

The '``call``' instruction is used to cause control flow to transfer to
a specified function, with its incoming arguments bound to the specified
values. Upon a '``ret``' instruction in the called function, control
flow continues with the instruction after the function call, and the
return value of the function is bound to the result argument.

Example:
""""""""

.. code-block:: llvm

      %retval = call i32 @test(i32 %argc)
      call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42)        ; yields i32
      %X = tail call i32 @foo()                                    ; yields i32
      %Y = tail call fastcc i32 @foo()  ; yields i32
      call void %foo(i8 97 signext)

      %struct.A = type { i32, i8 }
      %r = call %struct.A @foo()                        ; yields { 32, i8 }
      %gr = extractvalue %struct.A %r, 0                ; yields i32
      %gr1 = extractvalue %struct.A %r, 1               ; yields i8
      %Z = call void @foo() noreturn                    ; indicates that %foo never returns normally
      %ZZ = call zeroext i32 @bar()                     ; Return value is %zero extended

llvm treats calls to some functions with names and arguments that match
the standard C99 library as being the C99 library functions, and may
perform optimizations or generate code for them under that assumption.
This is something we'd like to change in the future to provide better
support for freestanding environments and non-C-based languages.

.. _i_va_arg:

'``va_arg``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <resultval> = va_arg <va_list*> <arglist>, <argty>

Overview:
"""""""""

The '``va_arg``' instruction is used to access arguments passed through
the "variable argument" area of a function call. It is used to implement
the ``va_arg`` macro in C.

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

This instruction takes a ``va_list*`` value and the type of the
argument. It returns a value of the specified argument type and
increments the ``va_list`` to point to the next argument. The actual
type of ``va_list`` is target specific.

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

The '``va_arg``' instruction loads an argument of the specified type
from the specified ``va_list`` and causes the ``va_list`` to point to
the next argument. For more information, see the variable argument
handling :ref:`Intrinsic Functions <int_varargs>`.

It is legal for this instruction to be called in a function which does
not take a variable number of arguments, for example, the ``vfprintf``
function.

``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic
function <intrinsics>` because it takes a type as an argument.

Example:
""""""""

See the :ref:`variable argument processing <int_varargs>` section.

Note that the code generator does not yet fully support va\_arg on many
targets. Also, it does not currently support va\_arg with aggregate
types on any target.

.. _i_landingpad:

'``landingpad``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+
      <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>*

      <clause> := catch <type> <value>
      <clause> := filter <array constant type> <array constant>

Overview:
"""""""""

The '``landingpad``' instruction is used by `LLVM's exception handling
system <ExceptionHandling.html#overview>`_ to specify that a basic block
is a landing pad --- one where the exception lands, and corresponds to the
code found in the ``catch`` portion of a ``try``/``catch`` sequence. It
defines values supplied by the personality function (``pers_fn``) upon
re-entry to the function. The ``resultval`` has the type ``resultty``.

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

This instruction takes a ``pers_fn`` value. This is the personality
function associated with the unwinding mechanism. The optional
``cleanup`` flag indicates that the landing pad block is a cleanup.

A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and
contains the global variable representing the "type" that may be caught
or filtered respectively. Unlike the ``catch`` clause, the ``filter``
clause takes an array constant as its argument. Use
"``[0 x i8**] undef``" for a filter which cannot throw. The
'``landingpad``' instruction must contain *at least* one ``clause`` or
the ``cleanup`` flag.

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

The '``landingpad``' instruction defines the values which are set by the
personality function (``pers_fn``) upon re-entry to the function, and
therefore the "result type" of the ``landingpad`` instruction. As with
calling conventions, how the personality function results are
represented in LLVM IR is target specific.

The clauses are applied in order from top to bottom. If two
``landingpad`` instructions are merged together through inlining, the
clauses from the calling function are appended to the list of clauses.
When the call stack is being unwound due to an exception being thrown,
the exception is compared against each ``clause`` in turn. If it doesn't
match any of the clauses, and the ``cleanup`` flag is not set, then
unwinding continues further up the call stack.

The ``landingpad`` instruction has several restrictions:

-  A landing pad block is a basic block which is the unwind destination
   of an '``invoke``' instruction.
-  A landing pad block must have a '``landingpad``' instruction as its
   first non-PHI instruction.
-  There can be only one '``landingpad``' instruction within the landing
   pad block.
-  A basic block that is not a landing pad block may not include a
   '``landingpad``' instruction.
-  All '``landingpad``' instructions in a function must have the same
   personality function.

Example:
""""""""

.. code-block:: llvm

      ;; A landing pad which can catch an integer.
      %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
               catch i8** @_ZTIi
      ;; A landing pad that is a cleanup.
      %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
               cleanup
      ;; A landing pad which can catch an integer and can only throw a double.
      %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
               catch i8** @_ZTIi
               filter [1 x i8**] [@_ZTId]

.. _intrinsics:

Intrinsic Functions
===================

LLVM supports the notion of an "intrinsic function". These functions
have well known names and semantics and are required to follow certain
restrictions. Overall, these intrinsics represent an extension mechanism
for the LLVM language that does not require changing all of the
transformations in LLVM when adding to the language (or the bitcode
reader/writer, the parser, etc...).

Intrinsic function names must all start with an "``llvm.``" prefix. This
prefix is reserved in LLVM for intrinsic names; thus, function names may
not begin with this prefix. Intrinsic functions must always be external
functions: you cannot define the body of intrinsic functions. Intrinsic
functions may only be used in call or invoke instructions: it is illegal
to take the address of an intrinsic function. Additionally, because
intrinsic functions are part of the LLVM language, it is required if any
are added that they be documented here.

Some intrinsic functions can be overloaded, i.e., the intrinsic
represents a family of functions that perform the same operation but on
different data types. Because LLVM can represent over 8 million
different integer types, overloading is used commonly to allow an
intrinsic function to operate on any integer type. One or more of the
argument types or the result type can be overloaded to accept any
integer type. Argument types may also be defined as exactly matching a
previous argument's type or the result type. This allows an intrinsic
function which accepts multiple arguments, but needs all of them to be
of the same type, to only be overloaded with respect to a single
argument or the result.

Overloaded intrinsics will have the names of its overloaded argument
types encoded into its function name, each preceded by a period. Only
those types which are overloaded result in a name suffix. Arguments
whose type is matched against another type do not. For example, the
``llvm.ctpop`` function can take an integer of any width and returns an
integer of exactly the same integer width. This leads to a family of
functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and
``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is
overloaded, and only one type suffix is required. Because the argument's
type is matched against the return type, it does not require its own
name suffix.

To learn how to add an intrinsic function, please see the `Extending
LLVM Guide <ExtendingLLVM.html>`_.

.. _int_varargs:

Variable Argument Handling Intrinsics
-------------------------------------

Variable argument support is defined in LLVM with the
:ref:`va_arg <i_va_arg>` instruction and these three intrinsic
functions. These functions are related to the similarly named macros
defined in the ``<stdarg.h>`` header file.

All of these functions operate on arguments that use a target-specific
value type "``va_list``". The LLVM assembly language reference manual
does not define what this type is, so all transformations should be
prepared to handle these functions regardless of the type used.

This example shows how the :ref:`va_arg <i_va_arg>` instruction and the
variable argument handling intrinsic functions are used.

.. code-block:: llvm

    define i32 @test(i32 %X, ...) {
      ; Initialize variable argument processing
      %ap = alloca i8*
      %ap2 = bitcast i8** %ap to i8*
      call void @llvm.va_start(i8* %ap2)

      ; Read a single integer argument
      %tmp = va_arg i8** %ap, i32

      ; Demonstrate usage of llvm.va_copy and llvm.va_end
      %aq = alloca i8*
      %aq2 = bitcast i8** %aq to i8*
      call void @llvm.va_copy(i8* %aq2, i8* %ap2)
      call void @llvm.va_end(i8* %aq2)