LangRef.rst

------------------

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:
""""""""""

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 after 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. Any stores into the memory
object following this intrinsic may be removed as dead.

'``llvm.invariant.start``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)

Overview:
"""""""""

The '``llvm.invariant.start``' intrinsic specifies that the contents of
a memory object will not change.

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 until an ``llvm.invariant.end`` that uses
the return value, the referenced memory location is constant and
unchanging.

'``llvm.invariant.end``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)

Overview:
"""""""""

The '``llvm.invariant.end``' intrinsic specifies that the contents of a
memory object are mutable.

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

The first argument is the matching ``llvm.invariant.start`` intrinsic.
The second argument is a constant integer representing the size of the
object, or -1 if it is variable sized and the third argument is a
pointer to the object.

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

This intrinsic indicates that the memory is mutable again.

General Intrinsics
------------------

This class of intrinsics is designed to be generic and has no specific
purpose.

'``llvm.var.annotation``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32  <int>)

Overview:
"""""""""

The '``llvm.var.annotation``' intrinsic.

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

The first argument is a pointer to a value, the second is a pointer to a
global string, the third is a pointer to a global string which is the
source file name, and the last argument is the line number.

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

This intrinsic allows annotation of local variables with arbitrary
strings. This can be useful for special purpose optimizations that want
to look for these annotations. These have no other defined use; they are
ignored by code generation and optimization.

'``llvm.annotation.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

This is an overloaded intrinsic. You can use '``llvm.annotation``' on
any integer bit width.

::

      declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32  <int>)
      declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32  <int>)
      declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32  <int>)
      declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32  <int>)
      declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32  <int>)

Overview:
"""""""""

The '``llvm.annotation``' intrinsic.

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

The first argument is an integer value (result of some expression), the
second is a pointer to a global string, the third is a pointer to a
global string which is the source file name, and the last argument is
the line number. It returns the value of the first argument.

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

This intrinsic allows annotations to be put on arbitrary expressions
with arbitrary strings. This can be useful for special purpose
optimizations that want to look for these annotations. These have no
other defined use; they are ignored by code generation and optimization.

'``llvm.trap``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.trap() noreturn nounwind

Overview:
"""""""""

The '``llvm.trap``' intrinsic.

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

None.

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

This intrinsic is lowered to the target dependent trap instruction. If
the target does not have a trap instruction, this intrinsic will be
lowered to a call of the ``abort()`` function.

'``llvm.debugtrap``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.debugtrap() nounwind

Overview:
"""""""""

The '``llvm.debugtrap``' intrinsic.

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

None.

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

This intrinsic is lowered to code which is intended to cause an
execution trap with the intention of requesting the attention of a
debugger.

'``llvm.stackprotector``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)

Overview:
"""""""""

The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it
onto the stack at ``slot``. The stack slot is adjusted to ensure that it
is placed on the stack before local variables.

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

The ``llvm.stackprotector`` intrinsic requires two pointer arguments.
The first argument is the value loaded from the stack guard
``@__stack_chk_guard``. The second variable is an ``alloca`` that has
enough space to hold the value of the guard.

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

This intrinsic causes the prologue/epilogue inserter to force the
position of the ``AllocaInst`` stack slot to be before local variables
on the stack. This is to ensure that if a local variable on the stack is
overwritten, it will destroy the value of the guard. When the function
exits, the guard on the stack is checked against the original guard. If
they are different, then the program aborts by calling the
``__stack_chk_fail()`` function.

'``llvm.objectsize``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>)
      declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>)

Overview:
"""""""""

The ``llvm.objectsize`` intrinsic is designed to provide information to
the optimizers to determine at compile time whether a) an operation
(like memcpy) will overflow a buffer that corresponds to an object, or
b) that a runtime check for overflow isn't necessary. An object in this
context means an allocation of a specific class, structure, array, or
other object.

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

The ``llvm.objectsize`` intrinsic takes two arguments. The first
argument is a pointer to or into the ``object``. The second argument is
a boolean and determines whether ``llvm.objectsize`` returns 0 (if true)
or -1 (if false) when the object size is unknown. The second argument
only accepts constants.

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

The ``llvm.objectsize`` intrinsic is lowered to a constant representing
the size of the object concerned. If the size cannot be determined at
compile time, ``llvm.objectsize`` returns ``i32/i64 -1 or 0`` (depending
on the ``min`` argument).

'``llvm.expect``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
      declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)

Overview:
"""""""""

The ``llvm.expect`` intrinsic provides information about expected (the
most probable) value of ``val``, which can be used by optimizers.

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

The ``llvm.expect`` intrinsic takes two arguments. The first argument is
a value. The second argument is an expected value, this needs to be a
constant value, variables are not allowed.

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

This intrinsic is lowered to the ``val``.

'``llvm.donothing``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Syntax:
"""""""

::

      declare void @llvm.donothing() nounwind readnone

Overview:
"""""""""

The ``llvm.donothing`` intrinsic doesn't perform any operation. It's the
only intrinsic that can be called with an invoke instruction.

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

None.

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

This intrinsic does nothing, and it's removed by optimizers and ignored
by codegen.