A model can also be specified in a alias, but then it only governs how
the alias is accessed. It will not have any effect in the aliasee.
+For platforms without linker support of ELF TLS model, the -femulated-tls
+flag can be used to generate GCC compatible emulated TLS code.
+
.. _namedtypes:
Structure Types
On an argument, this attribute indicates that the function does not write
through this pointer argument, even though it may write to the memory that
the pointer points to.
+``argmemonly``
+ This attribute indicates that the only memory accesses inside function are
+ loads and stores from objects pointed to by its pointer-typed arguments,
+ with arbitrary offsets. Or in other words, all memory operations in the
+ function can refer to memory only using pointers based on its function
+ arguments.
+ Note that ``argmemonly`` can be used together with ``readonly`` attribute
+ in order to specify that function reads only from its arguments.
``returns_twice``
This attribute indicates that this function can return twice. The C
``setjmp`` is an example of such a function. The compiler disables
LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`,
:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
-:ref:`frem <i_frem>`) have the following flags that can be set to enable
-otherwise unsafe floating point operations
+:ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`) have the following flags that can
+be set to enable otherwise unsafe floating point operations
``nnan``
No NaNs - Allow optimizations to assume the arguments and result are not
``sc`` instruction on the given subtarget (details vary).
- ``r``, ``d``, ``y``: A 32 or 64-bit GPR register.
- ``f``: A 32 or 64-bit FPU register (``F0-F31``), or a 128-bit MSA register
- (``W0-W31``).
+ (``W0-W31``). In the case of MSA registers, it is recommended to use the ``w``
+ argument modifier for compatibility with GCC.
- ``c``: A 32-bit or 64-bit GPR register suitable for indirect jump (always
``25``).
- ``l``: The ``lo`` register, 32 or 64-bit.
second word of a double-word memory operand. (On a big-endian system, ``D`` is
equivalent to ``L``, and on little-endian system, ``D`` is equivalent to
``M``.)
-- ``w``: No effect.
+- ``w``: No effect. Provided for compatibility with GCC which requires this
+ modifier in order to print MSA registers (``W0-W31``) with the ``f``
+ constraint.
NVPTX:
.. code-block:: llvm
- !0 = !DILocalVariable(tag: DW_TAG_arg_variable, name: "this", arg: 0,
+ !0 = !DILocalVariable(tag: DW_TAG_arg_variable, name: "this", arg: 1,
scope: !3, file: !2, line: 7, type: !3,
flags: DIFlagArtificial)
- !1 = !DILocalVariable(tag: DW_TAG_arg_variable, name: "x", arg: 1,
+ !1 = !DILocalVariable(tag: DW_TAG_arg_variable, name: "x", arg: 2,
scope: !4, file: !2, line: 7, type: !3)
- !1 = !DILocalVariable(tag: DW_TAG_auto_variable, name: "y",
+ !2 = !DILocalVariable(tag: DW_TAG_auto_variable, name: "y",
scope: !5, file: !2, line: 7, type: !3)
DIExpression
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>`', ':ref:`catchblock <i_catchblock>`',
-':ref:`catchendblock <i_catchendblock>`',
+':ref:`resume <i_resume>`', ':ref:`catchpad <i_catchpad>`',
+':ref:`catchendpad <i_catchendpad>`',
':ref:`catchret <i_catchret>`',
-':ref:`terminateblock <i_terminateblock>`',
+':ref:`cleanupret <i_cleanupret>`',
+':ref:`terminatepad <i_terminatepad>`',
and ':ref:`unreachable <i_unreachable>`'.
.. _i_ret:
resume { i8*, i32 } %exn
-.. _i_catchblock:
+.. _i_catchpad:
-'``catchblock``' Instruction
+'``catchpad``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Syntax:
::
- <resultval> = catch
block <resultty> [<args>*]
+ <resultval> = catch
pad <resultty> [<args>*]
to label <normal label> unwind label <exception label>
Overview:
"""""""""
-The '``catchblock``' instruction is used by `LLVM's exception handling
+The '``catchpad``' instruction is used by `LLVM's exception handling
system <ExceptionHandling.html#overview>`_ to specify that a basic block
is a catch block --- one where a personality routine attempts to transfer
control to catch an exception.
The ``args`` correspond to whatever information the personality
routine requires to know if this is an appropriate place to catch the
exception. Control is tranfered to the ``exception`` label if the
-``catchblock`` is not an appropriate handler for the in-flight exception.
+``catchpad`` is not an appropriate handler for the in-flight exception.
The ``normal`` label should contain the code found in the ``catch``
portion of a ``try``/``catch`` sequence. It defines values supplied by
the :ref:`personality function <personalityfn>` upon re-entry to the
The instruction takes a list of arbitrary values which are interpreted
by the :ref:`personality function <personalityfn>`.
-The ``catchblock`` must be provided a ``normal`` label to transfer control
-to if the ``catchblock`` matches the exception and an ``exception``
+The ``catchpad`` must be provided a ``normal`` label to transfer control
+to if the ``catchpad`` matches the exception and an ``exception``
label to transfer control to if it doesn't.
Semantics:
""""""""""
-The '``catchblock``' instruction defines the values which are set by the
+The '``catchpad``' instruction defines the values which are set by the
:ref:`personality function <personalityfn>` upon re-entry to the function, and
-therefore the "result type" of the ``catchblock`` instruction. As with
+therefore the "result type" of the ``catchpad`` instruction. As with
calling conventions, how the personality function results are
represented in LLVM IR is target specific.
the exception is compared against the ``args``. If it doesn't match,
then control is transfered to the ``exception`` basic block.
-The ``catchblock`` instruction has several restrictions:
+The ``catchpad`` instruction has several restrictions:
- A catch block is a basic block which is the unwind destination of
an exceptional instruction.
-- A catch block must have a '``catchblock``' instruction as its
+- A catch block must have a '``catchpad``' instruction as its
first non-PHI instruction.
-- There can be only one '``catchblock``' instruction within the
+- A catch block's ``exception`` edge must refer to a catch block or a
+ catch-end block.
+- There can be only one '``catchpad``' instruction within the
catch block.
- A basic block that is not a catch block may not include a
- '``catchblock``' instruction.
+ '``catchpad``' instruction.
+- It is undefined behavior for control to transfer from a ``catchpad`` to a
+ ``cleanupret`` without first executing a ``catchret`` and a subsequent
+ ``cleanuppad``.
+- It is undefined behavior for control to transfer from a ``catchpad`` to a
+ ``ret`` without first executing a ``catchret``.
Example:
""""""""
.. code-block:: llvm
;; A catch block which can catch an integer.
- %res = catchblock { i8*, i32 } [i8** @_ZTIi]
+ %res = catchpad { i8*, i32 } [i8** @_ZTIi]
to label %int.handler unwind label %terminate
-.. _i_catchendblock:
+.. _i_catchendpad:
-'``catchendblock``' Instruction
+'``catchendpad``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Syntax:
::
- catchendblock unwind label <nextaction>
- catchendblock unwind to caller
+ catchendpad unwind label <nextaction>
+ catchendpad unwind to caller
Overview:
"""""""""
-The '``catchendblock``' instruction is used by `LLVM's exception handling
+The '``catchendpad``' instruction is used by `LLVM's exception handling
system <ExceptionHandling.html#overview>`_ to communicate to the
:ref:`personality function <personalityfn>` which invokes are associated
-with a chain of :ref:`catchblock <i_catchblock>` instructions.
+with a chain of :ref:`catchpad <i_catchpad>` instructions.
The ``nextaction`` label indicates where control should transfer to if
-none of the ``catchblock`` instructions are suitable for catching the
+none of the ``catchpad`` instructions are suitable for catching the
in-flight exception.
If a ``nextaction`` label is not present, the instruction unwinds out of
-the function it is located in. The
-:ref:`personality function <personalityfn>` will look for an appropriate
-catch block in the caller.
+its parent function. The
+:ref:`personality function <personalityfn>` will continue processing
+exception handling actions in the caller.
Arguments:
""""""""""
The instruction optionally takes a label, ``nextaction``, indicating
-where control should transfer to if none of the constituent
-``catchblock`` instructions are suitable for the in-flight exception.
+where control should transfer to if none of the preceding
+``catchpad`` instructions are suitable for the in-flight exception.
Semantics:
""""""""""
When the call stack is being unwound due to an exception being thrown
-and none of the constituent ``catchblock`` instructions match, then
+and none of the constituent ``catchpad`` instructions match, then
control is transfered to ``nextaction`` if it is present. If it is not
present, control is transfered to the caller.
-The ``catchendblock`` instruction has several restrictions:
+The ``catchendpad`` instruction has several restrictions:
- A catch-end block is a basic block which is the unwind destination of
an exceptional instruction.
-- A catch-end block must have a '``catchendblock``' instruction as its
+- A catch-end block must have a '``catchendpad``' instruction as its
first non-PHI instruction.
-- There can be only one '``catchendblock``' instruction within the
+- There can be only one '``catchendpad``' instruction within the
catch block.
- A basic block that is not a catch-end block may not include a
- '``catchendblock``' instruction.
+ '``catchendpad``' instruction.
+- Exactly one catch block may unwind to a ``catchendpad``.
+- The unwind target of invokes between a ``catchpad`` and a
+ corresponding ``catchret`` must be its ``catchendpad``.
Example:
""""""""
.. code-block:: llvm
- catchendblock unwind label %terminate
- catchendblock unwind to caller
+ catchendpad unwind label %terminate
+ catchendpad unwind to caller
.. _i_catchret:
The '``catchret``' instruction ends the existing (in-flight) exception
whose unwinding was interrupted with a
-:ref:`catchblock <i_catchblock>` instruction and transfer control to
-``normal``.
+:ref:`catchpad <i_catchpad>` instruction.
+The :ref:`personality function <personalityfn>` gets a chance to execute
+arbitrary code to, for example, run a C++ destructor.
+Control then transfers to ``normal``.
Example:
""""""""
.. code-block:: llvm
- catchret unwind label %continue
+ catchret label %continue
.. _i_cleanupret:
""""""""""
The '``cleanupret``' instruction requires one argument, which must have the
-same type as the result of any '``cleanupblock``' instruction in the same
+same type as the result of any '``cleanuppad``' instruction in the same
function. It also has an optional successor, ``continue``.
Semantics:
""""""""""
The '``cleanupret``' instruction indicates to the
-:ref:`personality function <personalityfn>` that the
-:ref:`cleanupblock <i_cleanupblock>` it transfered control to has ended.
+:ref:`personality function <personalityfn>` that one
+:ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended.
It transfers control to ``continue`` or unwinds out of the function.
Example:
.. code-block:: llvm
+ cleanupret void unwind to caller
cleanupret { i8*, i32 } %exn unwind label %continue
-.. _i_terminateblock:
+.. _i_terminatepad:
-'``terminateblock``' Instruction
+'``terminatepad``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Syntax:
::
- terminateblock [<args>*] unwind label <exception label>
+ terminatepad [<args>*] unwind label <exception label>
+ terminatepad [<args>*] unwind to caller
Overview:
"""""""""
-The '``terminateblock``' instruction is used by `LLVM's exception handling
+The '``terminatepad``' instruction is used by `LLVM's exception handling
system <ExceptionHandling.html#overview>`_ to specify that a basic block
-is a terminate block --- one where a personality routine attempts to transfer
-control to terminate the program.
+is a terminate block --- one where a personality routine may decide to
+terminate the program.
The ``args`` correspond to whatever information the personality
routine requires to know if this is an appropriate place to terminate the
-program. Control is tranfered to the ``exception`` label if the
-``terminateblock`` is an appropriate handler for the in-flight exception.
-If the ``terminateblock`` is not an appropriate handler, execution of
-the program is terminated via
-:ref:`personality function <personalityfn>` specific means.
+program. Control is transferred to the ``exception`` label if the
+personality routine decides not to terminate the program for the
+in-flight exception.
Arguments:
""""""""""
The instruction takes a list of arbitrary values which are interpreted
by the :ref:`personality function <personalityfn>`.
-The ``terminateblock`` must be provided an ``exception`` label to
+The ``terminatepad`` may be given an ``exception`` label to
transfer control to if the in-flight exception matches the ``args``.
Semantics:
the exception is compared against the ``args``. If it matches,
then control is transfered to the ``exception`` basic block. Otherwise,
the program is terminated via personality-specific means. Typically,
-the first argument to ``terminateblock`` specifies what function the
+the first argument to ``terminatepad`` specifies what function the
personality should defer to in order to terminate the program.
-The ``terminateblock`` instruction has several restrictions:
+The ``terminatepad`` instruction has several restrictions:
- A terminate block is a basic block which is the unwind destination of
an exceptional instruction.
-- A terminate block must have a '``terminateblock``' instruction as its
+- A terminate block must have a '``terminatepad``' instruction as its
first non-PHI instruction.
-- There can be only one '``terminateblock``' instruction within the
+- There can be only one '``terminatepad``' instruction within the
terminate block.
- A basic block that is not a terminate block may not include a
- '``terminateblock``' instruction.
+ '``terminatepad``' instruction.
Example:
""""""""
.. code-block:: llvm
;; A terminate block which only permits integers.
- terminateblock [i8** @_ZTIi] unwind label %continue
+ terminatepad [i8** @_ZTIi] unwind label %continue
.. _i_unreachable:
::
- <result> = fcmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
+ <result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
Overview:
"""""""""
#. ``uno``: yields ``true`` if either operand is a QNAN.
#. ``true``: always yields ``true``, regardless of operands.
+The ``fcmp`` instruction can also optionally take any number of
+:ref:`fast-math flags <fastmath>`, which are optimization hints to enable
+otherwise unsafe floating point optimizations.
+
+Any set of fast-math flags are legal on an ``fcmp`` instruction, but the
+only flags that have any effect on its semantics are those that allow
+assumptions to be made about the values of input arguments; namely
+``nnan``, ``ninf``, and ``nsz``. See :ref:`fastmath` for more information.
+
Example:
""""""""
catch i8** @_ZTIi
filter [1 x i8**] [@_ZTId]
-.. _i_cleanupblock:
+.. _i_cleanuppad:
-'``cleanupblock``' Instruction
+'``cleanuppad``' Instruction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Syntax:
::
- <resultval> = cleanup
block <resultty> [<args>*]
+ <resultval> = cleanup
pad <resultty> [<args>*]
Overview:
"""""""""
-The '``cleanupblock``' instruction is used by `LLVM's exception handling
+The '``cleanuppad``' instruction is used by `LLVM's exception handling
system <ExceptionHandling.html#overview>`_ to specify that a basic block
is a cleanup block --- one where a personality routine attempts to
transfer control to run cleanup actions.
The ``args`` correspond to whatever additional
information the :ref:`personality function <personalityfn>` requires to
execute the cleanup.
-:ref:`personality function <personalityfn>` upon re-entry to the
-function. The ``resultval`` has the type ``resultty``.
+The ``resultval`` has the type ``resultty``.
Arguments:
""""""""""
Semantics:
""""""""""
-The '``cleanupblock``' instruction defines the values which are set by the
+The '``cleanuppad``' instruction defines the values which are set by the
:ref:`personality function <personalityfn>` upon re-entry to the function, and
-therefore the "result type" of the ``cleanupblock`` instruction. As with
+therefore the "result type" of the ``cleanuppad`` instruction. As with
calling conventions, how the personality function results are
represented in LLVM IR is target specific.
When the call stack is being unwound due to an exception being thrown,
the :ref:`personality function <personalityfn>` transfers control to the
-``cleanupblock`` with the aid of the personality-specific arguments.
+``cleanuppad`` with the aid of the personality-specific arguments.
-The ``cleanupblock`` instruction has several restrictions:
+The ``cleanuppad`` instruction has several restrictions:
- A cleanup block is a basic block which is the unwind destination of
an exceptional instruction.
-- A cleanup block must have a '``cleanupblock``' instruction as its
+- A cleanup block must have a '``cleanuppad``' instruction as its
first non-PHI instruction.
-- There can be only one '``cleanupblock``' instruction within the
+- There can be only one '``cleanuppad``' instruction within the
cleanup block.
- A basic block that is not a cleanup block may not include a
- '``cleanupblock``' instruction.
+ '``cleanuppad``' instruction.
+- It is undefined behavior for control to transfer from a ``cleanuppad`` to a
+ ``catchret`` without first executing a ``cleanupret`` and a subsequent
+ ``catchpad``.
+- It is undefined behavior for control to transfer from a ``cleanuppad`` to a
+ ``ret`` without first executing a ``cleanupret``.
Example:
""""""""
.. code-block:: llvm
- %res = cleanupblock { i8*, i32 } [label %nextaction]
+ %res = cleanuppad { i8*, i32 } [label %nextaction]
.. _intrinsics:
Specialised Arithmetic Intrinsics
---------------------------------
+'``llvm.canonicalize.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare float @llvm.canonicalize.f32(float %a)
+ declare double @llvm.canonicalize.f64(double %b)
+
+Overview:
+"""""""""
+
+The '``llvm.canonicalize.*``' intrinsic returns the platform specific canonical
+encoding of a floating point number. This canonicalization is useful for
+implementing certain numeric primitives such as frexp. The canonical encoding is
+defined by IEEE-754-2008 to be:
+
+::
+
+ 2.1.8 canonical encoding: The preferred encoding of a floating-point
+ representation in a format. Applied to declets, significands of finite
+ numbers, infinities, and NaNs, especially in decimal formats.
+
+This operation can also be considered equivalent to the IEEE-754-2008
+conversion of a floating-point value to the same format. NaNs are handled
+according to section 6.2.
+
+Examples of non-canonical encodings:
+
+- x87 pseudo denormals, pseudo NaNs, pseudo Infinity, Unnormals. These are
+ converted to a canonical representation per hardware-specific protocol.
+- Many normal decimal floating point numbers have non-canonical alternative
+ encodings.
+- Some machines, like GPUs or ARMv7 NEON, do not support subnormal values.
+ These are treated as non-canonical encodings of zero and with be flushed to
+ a zero of the same sign by this operation.
+
+Note that per IEEE-754-2008 6.2, systems that support signaling NaNs with
+default exception handling must signal an invalid exception, and produce a
+quiet NaN result.
+
+This function should always be implementable as multiplication by 1.0, provided
+that the compiler does not constant fold the operation. Likewise, division by
+1.0 and ``llvm.minnum(x, x)`` are possible implementations. Addition with
+-0.0 is also sufficient provided that the rounding mode is not -Infinity.
+
+``@llvm.canonicalize`` must preserve the equality relation. That is:
+
+- ``(@llvm.canonicalize(x) == x)`` is equivalent to ``(x == x)``
+- ``(@llvm.canonicalize(x) == @llvm.canonicalize(y))`` is equivalent to
+ to ``(x == y)``
+
+Additionally, the sign of zero must be conserved:
+``@llvm.canonicalize(-0.0) = -0.0`` and ``@llvm.canonicalize(+0.0) = +0.0``
+
+The payload bits of a NaN must be conserved, with two exceptions.
+First, environments which use only a single canonical representation of NaN
+must perform said canonicalization. Second, SNaNs must be quieted per the
+usual methods.
+
+The canonicalization operation may be optimized away if:
+
+- The input is known to be canonical. For example, it was produced by a
+ floating-point operation that is required by the standard to be canonical.
+- The result is consumed only by (or fused with) other floating-point
+ operations. That is, the bits of the floating point value are not examined.
+
'``llvm.fmuladd.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
%r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c
+
+'``llvm.uabsdiff.*``' and '``llvm.sabsdiff.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+This is an overloaded intrinsic. The loaded data is a vector of any integer bit width.
+
+.. code-block:: llvm
+
+ declare <4 x integer> @llvm.uabsdiff.v4i32(<4 x integer> %a, <4 x integer> %b)
+
+
+Overview:
+"""""""""
+
+The ``llvm.uabsdiff`` intrinsic returns a vector result of the absolute difference of the two operands,
+treating them both as unsigned integers.
+
+The ``llvm.sabsdiff`` intrinsic returns a vector result of the absolute difference of the two operands,
+treating them both as signed integers.
+
+.. note::
+
+ These intrinsics are primarily used during the code generation stage of compilation.
+ They are generated by compiler passes such as the Loop and SLP vectorizers.it is not
+ recommended for users to create them manually.
+
+Arguments:
+""""""""""
+
+Both intrinsics take two integer of the same bitwidth.
+
+Semantics:
+""""""""""
+
+The expression::
+
+ call <4 x i32> @llvm.uabsdiff.v4i32(<4 x i32> %a, <4 x i32> %b)
+
+is equivalent to::
+
+ %sub = sub <4 x i32> %a, %b
+ %ispos = icmp ugt <4 x i32> %sub, <i32 -1, i32 -1, i32 -1, i32 -1>
+ %neg = sub <4 x i32> zeroinitializer, %sub
+ %1 = select <4 x i1> %ispos, <4 x i32> %sub, <4 x i32> %neg
+
+Similarly the expression::
+
+ call <4 x i32> @llvm.sabsdiff.v4i32(<4 x i32> %a, <4 x i32> %b)
+
+is equivalent to::
+
+ %sub = sub nsw <4 x i32> %a, %b
+ %ispos = icmp sgt <4 x i32> %sub, <i32 -1, i32 -1, i32 -1, i32 -1>
+ %neg = sub nsw <4 x i32> zeroinitializer, %sub
+ %1 = select <4 x i1> %ispos, <4 x i32> %sub, <4 x i32> %neg
+
+
Half Precision Floating Point Intrinsics
----------------------------------------
projects / oota-llvm.git / blobdiff