LangRef.rst

"""""""""

The '``llvm.fabs.*``' intrinsics return the absolute value of the
operand.

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

The argument and return value are floating point numbers of the same
type.

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

This function returns the same values as the libm ``fabs`` functions
would, and handles error conditions in the same way.

'``llvm.floor.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.floor`` on any
floating point or vector of floating point type. Not all targets support
all types however.

::

      declare float     @llvm.floor.f32(float  %Val)
      declare double    @llvm.floor.f64(double %Val)
      declare x86_fp80  @llvm.floor.f80(x86_fp80  %Val)
      declare fp128     @llvm.floor.f128(fp128 %Val)
      declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128  %Val)

Overview:
"""""""""

The '``llvm.floor.*``' intrinsics return the floor of the operand.

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

The argument and return value are floating point numbers of the same
type.

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

This function returns the same values as the libm ``floor`` functions
would, and handles error conditions in the same way.

'``llvm.ceil.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.ceil`` on any
floating point or vector of floating point type. Not all targets support
all types however.

::

      declare float     @llvm.ceil.f32(float  %Val)
      declare double    @llvm.ceil.f64(double %Val)
      declare x86_fp80  @llvm.ceil.f80(x86_fp80  %Val)
      declare fp128     @llvm.ceil.f128(fp128 %Val)
      declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128  %Val)

Overview:
"""""""""

The '``llvm.ceil.*``' intrinsics return the ceiling of the operand.

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

The argument and return value are floating point numbers of the same
type.

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

This function returns the same values as the libm ``ceil`` functions
would, and handles error conditions in the same way.

'``llvm.trunc.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.trunc`` on any
floating point or vector of floating point type. Not all targets support
all types however.

::

      declare float     @llvm.trunc.f32(float  %Val)
      declare double    @llvm.trunc.f64(double %Val)
      declare x86_fp80  @llvm.trunc.f80(x86_fp80  %Val)
      declare fp128     @llvm.trunc.f128(fp128 %Val)
      declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128  %Val)

Overview:
"""""""""

The '``llvm.trunc.*``' intrinsics returns the operand rounded to the
nearest integer not larger in magnitude than the operand.

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

The argument and return value are floating point numbers of the same
type.

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

This function returns the same values as the libm ``trunc`` functions
would, and handles error conditions in the same way.

'``llvm.rint.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.rint`` on any
floating point or vector of floating point type. Not all targets support
all types however.

::

      declare float     @llvm.rint.f32(float  %Val)
      declare double    @llvm.rint.f64(double %Val)
      declare x86_fp80  @llvm.rint.f80(x86_fp80  %Val)
      declare fp128     @llvm.rint.f128(fp128 %Val)
      declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128  %Val)

Overview:
"""""""""

The '``llvm.rint.*``' intrinsics returns the operand rounded to the
nearest integer. It may raise an inexact floating-point exception if the
operand isn't an integer.

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

The argument and return value are floating point numbers of the same
type.

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

This function returns the same values as the libm ``rint`` functions
would, and handles error conditions in the same way.

'``llvm.nearbyint.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any
floating point or vector of floating point type. Not all targets support
all types however.

::

      declare float     @llvm.nearbyint.f32(float  %Val)
      declare double    @llvm.nearbyint.f64(double %Val)
      declare x86_fp80  @llvm.nearbyint.f80(x86_fp80  %Val)
      declare fp128     @llvm.nearbyint.f128(fp128 %Val)
      declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128  %Val)

Overview:
"""""""""

The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the
nearest integer.

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

The argument and return value are floating point numbers of the same
type.

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

This function returns the same values as the libm ``nearbyint``
functions would, and handles error conditions in the same way.

Bit Manipulation Intrinsics
---------------------------

LLVM provides intrinsics for a few important bit manipulation
operations. These allow efficient code generation for some algorithms.

'``llvm.bswap.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic function. You can use bswap on any
integer type that is an even number of bytes (i.e. BitWidth % 16 == 0).

::

      declare i16 @llvm.bswap.i16(i16 <id>)
      declare i32 @llvm.bswap.i32(i32 <id>)
      declare i64 @llvm.bswap.i64(i64 <id>)

Overview:
"""""""""

The '``llvm.bswap``' family of intrinsics is used to byte swap integer
values with an even number of bytes (positive multiple of 16 bits).
These are useful for performing operations on data that is not in the
target's native byte order.

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

The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high
and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32``
intrinsic returns an i32 value that has the four bytes of the input i32
swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the
returned i32 will have its bytes in 3, 2, 1, 0 order. The
``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this
concept to additional even-byte lengths (6 bytes, 8 bytes and more,
respectively).

'``llvm.ctpop.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use llvm.ctpop on any integer
bit width, or on any vector with integer elements. Not all targets
support all bit widths or vector types, however.

::

      declare i8 @llvm.ctpop.i8(i8  <src>)
      declare i16 @llvm.ctpop.i16(i16 <src>)
      declare i32 @llvm.ctpop.i32(i32 <src>)
      declare i64 @llvm.ctpop.i64(i64 <src>)
      declare i256 @llvm.ctpop.i256(i256 <src>)
      declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)

Overview:
"""""""""

The '``llvm.ctpop``' family of intrinsics counts the number of bits set
in a value.

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

The only argument is the value to be counted. The argument may be of any
integer type, or a vector with integer elements. The return type must
match the argument type.

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

The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within
each element of a vector.

'``llvm.ctlz.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any
integer bit width, or any vector whose elements are integers. Not all
targets support all bit widths or vector types, however.

::

      declare i8   @llvm.ctlz.i8  (i8   <src>, i1 <is_zero_undef>)
      declare i16  @llvm.ctlz.i16 (i16  <src>, i1 <is_zero_undef>)
      declare i32  @llvm.ctlz.i32 (i32  <src>, i1 <is_zero_undef>)
      declare i64  @llvm.ctlz.i64 (i64  <src>, i1 <is_zero_undef>)
      declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
      declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)

Overview:
"""""""""

The '``llvm.ctlz``' family of intrinsic functions counts the number of
leading zeros in a variable.

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

The first argument is the value to be counted. This argument may be of
any integer type, or a vectory with integer element type. The return
type must match the first argument type.

The second argument must be a constant and is a flag to indicate whether
the intrinsic should ensure that a zero as the first argument produces a
defined result. Historically some architectures did not provide a
defined result for zero values as efficiently, and many algorithms are
now predicated on avoiding zero-value inputs.

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

The '``llvm.ctlz``' intrinsic counts the leading (most significant)
zeros in a variable, or within each element of the vector. If
``src == 0`` then the result is the size in bits of the type of ``src``
if ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
``llvm.ctlz(i32 2) = 30``.

'``llvm.cttz.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.cttz`` on any
integer bit width, or any vector of integer elements. Not all targets
support all bit widths or vector types, however.

::

      declare i8   @llvm.cttz.i8  (i8   <src>, i1 <is_zero_undef>)
      declare i16  @llvm.cttz.i16 (i16  <src>, i1 <is_zero_undef>)
      declare i32  @llvm.cttz.i32 (i32  <src>, i1 <is_zero_undef>)
      declare i64  @llvm.cttz.i64 (i64  <src>, i1 <is_zero_undef>)
      declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
      declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)

Overview:
"""""""""

The '``llvm.cttz``' family of intrinsic functions counts the number of
trailing zeros.

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

The first argument is the value to be counted. This argument may be of
any integer type, or a vectory with integer element type. The return
type must match the first argument type.

The second argument must be a constant and is a flag to indicate whether
the intrinsic should ensure that a zero as the first argument produces a
defined result. Historically some architectures did not provide a
defined result for zero values as efficiently, and many algorithms are
now predicated on avoiding zero-value inputs.

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

The '``llvm.cttz``' intrinsic counts the trailing (least significant)
zeros in a variable, or within each element of a vector. If ``src == 0``
then the result is the size in bits of the type of ``src`` if
``is_zero_undef == 0`` and ``undef`` otherwise. For example,
``llvm.cttz(2) = 1``.

Arithmetic with Overflow Intrinsics
-----------------------------------

LLVM provides intrinsics for some arithmetic with overflow operations.

'``llvm.sadd.with.overflow.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``
on any integer bit width.

::

      declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
      declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
      declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)

Overview:
"""""""""

The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
a signed addition of the two arguments, and indicate whether an overflow
occurred during the signed summation.

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

The arguments (%a and %b) and the first element of the result structure
may be of integer types of any bit width, but they must have the same
bit width. The second element of the result structure must be of type
``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
addition.

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

The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
a signed addition of the two variables. They return a structure — the
first element of which is the signed summation, and the second element
of which is a bit specifying if the signed summation resulted in an
overflow.

Examples:
"""""""""

.. code-block:: llvm

      %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
      %sum = extractvalue {i32, i1} %res, 0
      %obit = extractvalue {i32, i1} %res, 1
      br i1 %obit, label %overflow, label %normal

'``llvm.uadd.with.overflow.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow``
on any integer bit width.

::

      declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
      declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
      declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)

Overview:
"""""""""

The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
an unsigned addition of the two arguments, and indicate whether a carry
occurred during the unsigned summation.

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

The arguments (%a and %b) and the first element of the result structure
may be of integer types of any bit width, but they must have the same
bit width. The second element of the result structure must be of type
``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
addition.

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

The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
an unsigned addition of the two arguments. They return a structure — the
first element of which is the sum, and the second element of which is a
bit specifying if the unsigned summation resulted in a carry.

Examples:
"""""""""

.. code-block:: llvm

      %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
      %sum = extractvalue {i32, i1} %res, 0
      %obit = extractvalue {i32, i1} %res, 1
      br i1 %obit, label %carry, label %normal

'``llvm.ssub.with.overflow.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow``
on any integer bit width.

::

      declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
      declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
      declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)

Overview:
"""""""""

The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
a signed subtraction of the two arguments, and indicate whether an
overflow occurred during the signed subtraction.

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

The arguments (%a and %b) and the first element of the result structure
may be of integer types of any bit width, but they must have the same
bit width. The second element of the result structure must be of type
``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
subtraction.

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

The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
a signed subtraction of the two arguments. They return a structure — the
first element of which is the subtraction, and the second element of
which is a bit specifying if the signed subtraction resulted in an
overflow.

Examples:
"""""""""

.. code-block:: llvm

      %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
      %sum = extractvalue {i32, i1} %res, 0
      %obit = extractvalue {i32, i1} %res, 1
      br i1 %obit, label %overflow, label %normal

'``llvm.usub.with.overflow.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow``
on any integer bit width.

::

      declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
      declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
      declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)

Overview:
"""""""""

The '``llvm.usub.with.overflow``' family of intrinsic functions perform
an unsigned subtraction of the two arguments, and indicate whether an
overflow occurred during the unsigned subtraction.

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

The arguments (%a and %b) and the first element of the result structure
may be of integer types of any bit width, but they must have the same
bit width. The second element of the result structure must be of type
``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
subtraction.

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

The '``llvm.usub.with.overflow``' family of intrinsic functions perform
an unsigned subtraction of the two arguments. They return a structure —
the first element of which is the subtraction, and the second element of
which is a bit specifying if the unsigned subtraction resulted in an
overflow.

Examples:
"""""""""

.. code-block:: llvm

      %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
      %sum = extractvalue {i32, i1} %res, 0
      %obit = extractvalue {i32, i1} %res, 1
      br i1 %obit, label %overflow, label %normal

'``llvm.smul.with.overflow.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow``
on any integer bit width.

::

      declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
      declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
      declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)

Overview:
"""""""""

The '``llvm.smul.with.overflow``' family of intrinsic functions perform
a signed multiplication of the two arguments, and indicate whether an
overflow occurred during the signed multiplication.

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

The arguments (%a and %b) and the first element of the result structure
may be of integer types of any bit width, but they must have the same
bit width. The second element of the result structure must be of type
``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
multiplication.

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

The '``llvm.smul.with.overflow``' family of intrinsic functions perform
a signed multiplication of the two arguments. They return a structure —
the first element of which is the multiplication, and the second element
of which is a bit specifying if the signed multiplication resulted in an
overflow.

Examples:
"""""""""

.. code-block:: llvm

      %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
      %sum = extractvalue {i32, i1} %res, 0
      %obit = extractvalue {i32, i1} %res, 1
      br i1 %obit, label %overflow, label %normal

'``llvm.umul.with.overflow.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow``
on any integer bit width.

::

      declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
      declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
      declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)

Overview:
"""""""""

The '``llvm.umul.with.overflow``' family of intrinsic functions perform
a unsigned multiplication of the two arguments, and indicate whether an
overflow occurred during the unsigned multiplication.

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

The arguments (%a and %b) and the first element of the result structure
may be of integer types of any bit width, but they must have the same
bit width. The second element of the result structure must be of type
``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
multiplication.

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

The '``llvm.umul.with.overflow``' family of intrinsic functions perform
an unsigned multiplication of the two arguments. They return a structure
— the first element of which is the multiplication, and the second
element of which is a bit specifying if the unsigned multiplication
resulted in an overflow.

Examples:
"""""""""

.. code-block:: llvm

      %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
      %sum = extractvalue {i32, i1} %res, 0
      %obit = extractvalue {i32, i1} %res, 1
      br i1 %obit, label %overflow, label %normal

Specialised Arithmetic Intrinsics
---------------------------------

'``llvm.fmuladd.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
      declare double @llvm.fmuladd.f64(double %a, double %b, double %c)

Overview:
"""""""""

The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add
expressions that can be fused if the code generator determines that the
fused expression would be legal and efficient.

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

The '``llvm.fmuladd.*``' intrinsics each take three arguments: two
multiplicands, a and b, and an addend c.

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

The expression:

::

      %0 = call float @llvm.fmuladd.f32(%a, %b, %c)

is equivalent to the expression a \* b + c, except that rounding will
not be performed between the multiplication and addition steps if the
code generator fuses the operations. Fusion is not guaranteed, even if
the target platform supports it. If a fused multiply-add is required the
corresponding llvm.fma.\* intrinsic function should be used instead.

Examples:
"""""""""

.. code-block:: llvm

      %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields {float}:r2 = (a * b) + c

Half Precision Floating Point Intrinsics
----------------------------------------

For most target platforms, half precision floating point is a
storage-only format. This means that it is a dense encoding (in memory)
but does not support computation in the format.

This means that code must first load the half-precision floating point
value as an i16, then convert it to float with
:ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can
then be performed on the float value (including extending to double
etc). To store the value back to memory, it is first converted to float
if needed, then converted to i16 with
:ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an
i16 value.

.. _int_convert_to_fp16:

'``llvm.convert.to.fp16``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare i16 @llvm.convert.to.fp16(f32 %a)

Overview:
"""""""""

The '``llvm.convert.to.fp16``' intrinsic function performs a conversion
from single precision floating point format to half precision floating
point format.

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

The intrinsic function contains single argument - the value to be
converted.

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

The '``llvm.convert.to.fp16``' intrinsic function performs a conversion
from single precision floating point format to half precision floating
point format. The return value is an ``i16`` which contains the
converted number.

Examples:
"""""""""

.. code-block:: llvm

      %res = call i16 @llvm.convert.to.fp16(f32 %a)
      store i16 %res, i16* @x, align 2

.. _int_convert_from_fp16:

'``llvm.convert.from.fp16``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare f32 @llvm.convert.from.fp16(i16 %a)

Overview:
"""""""""

The '``llvm.convert.from.fp16``' intrinsic function performs a
conversion from half precision floating point format to single precision
floating point format.

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

The intrinsic function contains single argument - the value to be
converted.

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

The '``llvm.convert.from.fp16``' intrinsic function performs a
conversion from half single precision floating point format to single
precision floating point format. The input half-float value is
represented by an ``i16`` value.

Examples:
"""""""""

.. code-block:: llvm

      %a = load i16* @x, align 2
      %res = call f32 @llvm.convert.from.fp16(i16 %a)

Debugger Intrinsics
-------------------

The LLVM debugger intrinsics (which all start with ``llvm.dbg.``
prefix), are described in the `LLVM Source Level
Debugging <SourceLevelDebugging.html#format_common_intrinsics>`_
document.

Exception Handling Intrinsics
-----------------------------

The LLVM exception handling intrinsics (which all start with
``llvm.eh.`` prefix), are described in the `LLVM Exception
Handling <ExceptionHandling.html#format_common_intrinsics>`_ document.

.. _int_trampoline:

Trampoline Intrinsics
---------------------

These intrinsics make it possible to excise one parameter, marked with
the :ref:`nest <nest>` attribute, from a function. The result is a
callable function pointer lacking the nest parameter - the caller does
not need to provide a value for it. Instead, the value to use is stored
in advance in a "trampoline", a block of memory usually allocated on the
stack, which also contains code to splice the nest value into the
argument list. This is used to implement the GCC nested function address
extension.

For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)``
then the resulting function pointer has signature ``i32 (i32, i32)*``.
It can be created as follows:

.. code-block:: llvm

      %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
      %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
      call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
      %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
      %fp = bitcast i8* %p to i32 (i32, i32)*

The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to
``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``.

.. _int_it:

'``llvm.init.trampoline``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)

Overview:
"""""""""

This fills the memory pointed to by ``tramp`` with executable code,
turning it into a trampoline.

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

The ``llvm.init.trampoline`` intrinsic takes three arguments, all
pointers. The ``tramp`` argument must point to a sufficiently large and
sufficiently aligned block of memory; this memory is written to by the
intrinsic. Note that the size and the alignment are target-specific -
LLVM currently provides no portable way of determining them, so a
front-end that generates this intrinsic needs to have some
target-specific knowledge. The ``func`` argument must hold a function
bitcast to an ``i8*``.

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

The block of memory pointed to by ``tramp`` is filled with target
dependent code, turning it into a function. Then ``tramp`` needs to be
passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can
be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new
function's signature is the same as that of ``func`` with any arguments
marked with the ``nest`` attribute removed. At most one such ``nest``
argument is allowed, and it must be of pointer type. Calling the new
function is equivalent to calling ``func`` with the same argument list,
but with ``nval`` used for the missing ``nest`` argument. If, after
calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is
modified, then the effect of any later call to the returned function
pointer is undefined.

.. _int_at:

'``llvm.adjust.trampoline``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare i8* @llvm.adjust.trampoline(i8* <tramp>)

Overview:
"""""""""

This performs any required machine-specific adjustment to the address of
a trampoline (passed as ``tramp``).

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

``tramp`` must point to a block of memory which already has trampoline
code filled in by a previous call to
:ref:`llvm.init.trampoline <int_it>`.

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

On some architectures the address of the code to be executed needs to be
different to the address where the trampoline is actually stored. This
intrinsic returns the executable address corresponding to ``tramp``
after performing the required machine specific adjustments. The pointer
returned can then be :ref:`bitcast and executed <int_trampoline>`.

Memory Use Markers
------------------

This class of intrinsics exists to information about the lifetime of
memory objects and ranges where variables are immutable.

'``llvm.lifetime.start``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)

Overview:
"""""""""

The '``llvm.lifetime.start``' intrinsic specifies the start of a memory
object's lifetime.

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

The first argument is a constant integer representing the size of the
object, or -1 if it is variable sized. The second argument is a pointer
to the object.

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

This intrinsic indicates that before this point in the code, the value
of the memory pointed to by ``ptr`` is dead. This means that it is known
to never be used and has an undefined value. A load from the pointer
that precedes this intrinsic can be replaced with ``'undef'``.

'``llvm.lifetime.end``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)

Overview:
"""""""""

The '``llvm.lifetime.end``' intrinsic specifies the end of a memory
object's lifetime.

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