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:`catchret <i_catchret>`',
-':ref:`cleanupret <i_cleanupret>`',
-':ref:`terminateblock <i_terminateblock>`',
-and ':ref:`unreachable <i_unreachable>`'.
+':ref:`resume <i_resume>`', and ':ref:`unreachable <i_unreachable>`'.
.. _i_ret:
resume { i8*, i32 } %exn
-.. _i_catchblock:
-
-'``catchblock``' Instruction
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Syntax:
-"""""""
-
-::
-
- <resultval> = catchblock <resultty> [<args>*]
- to label <normal label> unwind label <exception label>
-
-Overview:
-"""""""""
-
-The '``catchblock``' 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.
-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
-function. The ``resultval`` has the type ``resultty``.
-
-Arguments:
-""""""""""
-
-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``
-label to transfer control to if it doesn't.
-
-Semantics:
-""""""""""
-
-The '``catchblock``' 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
-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 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:
-
-- 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
- first non-PHI instruction.
-- A catch block's ``exception`` edge must refer to a catch block or a
- catch-end block.
-- There can be only one '``catchblock``' instruction within the
- catch block.
-- A basic block that is not a catch block may not include a
- '``catchblock``' instruction.
-
-Example:
-""""""""
-
-.. code-block:: llvm
-
- ;; A catch block which can catch an integer.
- %res = catchblock { i8*, i32 } [i8** @_ZTIi]
- to label %int.handler unwind label %terminate
-
-.. _i_catchendblock:
-
-'``catchendblock``' Instruction
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Syntax:
-"""""""
-
-::
-
- catchendblock unwind label <nextaction>
- catchendblock unwind to caller
-
-Overview:
-"""""""""
-
-The '``catchendblock``' 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.
-
-The ``nextaction`` label indicates where control should transfer to if
-none of the ``catchblock`` instructions are suitable for catching the
-in-flight exception.
-
-If a ``nextaction`` label is not present, the instruction unwinds out of
-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 preceding
-``catchblock`` 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
-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:
-
-- 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
- first non-PHI instruction.
-- There can be only one '``catchendblock``' instruction within the
- catch block.
-- A basic block that is not a catch-end block may not include a
- '``catchendblock``' instruction.
-- Exactly one catch block may unwind to a ``catchendblock``.
-
-Example:
-""""""""
-
-.. code-block:: llvm
-
- catchendblock unwind label %terminate
- catchendblock unwind to caller
-
-.. _i_catchret:
-
-'``catchret``' Instruction
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Syntax:
-"""""""
-
-::
-
- catchret label <normal>
-
-Overview:
-"""""""""
-
-The '``catchret``' instruction is a terminator instruction that has a
-single successor.
-
-
-Arguments:
-""""""""""
-
-The '``catchret``' instruction requires one argument which specifies
-where control will transfer to next.
-
-Semantics:
-""""""""""
-
-The '``catchret``' instruction ends the existing (in-flight) exception
-whose unwinding was interrupted with a
-:ref:`catchblock <i_catchblock>` 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 label %continue
-
-.. _i_cleanupret:
-
-'``cleanupret``' Instruction
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Syntax:
-"""""""
-
-::
-
- cleanupret <type> <value> unwind label <continue>
- cleanupret <type> <value> unwind to caller
-
-Overview:
-"""""""""
-
-The '``cleanupret``' instruction is a terminator instruction that has
-an optional successor.
-
-
-Arguments:
-""""""""""
-
-The '``cleanupret``' instruction requires one argument, which must have the
-same type as the result of any '``cleanupblock``' instruction in the same
-function. It also has an optional successor, ``continue``.
-
-Semantics:
-""""""""""
-
-The '``cleanupret``' instruction indicates to the
-:ref:`personality function <personalityfn>` that one
-:ref:`cleanupblock <i_cleanupblock>` 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:
-
-'``terminateblock``' Instruction
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Syntax:
-"""""""
-
-::
-
- terminateblock [<args>*] unwind label <exception label>
- terminateblock [<args>*] unwind to caller
-
-Overview:
-"""""""""
-
-The '``terminateblock``' 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 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 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`` may be given an ``exception`` label to
-transfer control to if the in-flight exception matches the ``args``.
-
-Semantics:
-""""""""""
-
-When the call stack is being unwound due to an exception being thrown,
-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
-personality should defer to in order to terminate the program.
-
-The ``terminateblock`` 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
- first non-PHI instruction.
-- There can be only one '``terminateblock``' instruction within the
- terminate block.
-- A basic block that is not a terminate block may not include a
- '``terminateblock``' instruction.
-
-Example:
-""""""""
-
-.. code-block:: llvm
-
- ;; A terminate block which only permits integers.
- terminateblock [i8** @_ZTIi] unwind label %continue
-
.. _i_unreachable:
'``unreachable``' Instruction
::
- <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:
-
-'``cleanupblock``' Instruction
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Syntax:
-"""""""
-
-::
-
- <resultval> = cleanupblock <resultty> [<args>*]
-
-Overview:
-"""""""""
-
-The '``cleanupblock``' 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.
-The ``resultval`` has the type ``resultty``.
-
-Arguments:
-""""""""""
-
-The instruction takes a list of arbitrary values which are interpreted
-by the :ref:`personality function <personalityfn>`.
-
-Semantics:
-""""""""""
-
-The '``cleanupblock``' 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
-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.
-
-The ``cleanupblock`` 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
- first non-PHI instruction.
-- There can be only one '``cleanupblock``' instruction within the
- cleanup block.
-- A basic block that is not a cleanup block may not include a
- '``cleanupblock``' instruction.
-
-Example:
-""""""""
-
-.. code-block:: llvm
-
- %res = cleanupblock { i8*, i32 } [label %nextaction]
-
.. _intrinsics:
Intrinsic Functions
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
----------------------------------------