""""""""""""""
``DILexicalBlock`` nodes describe nested blocks within a :ref:`subprogram
-<DISubprogram>`. The line number and column numbers are used to dinstinguish
+<DISubprogram>`. The line number and column numbers are used to distinguish
two lexical blocks at same depth. They are valid targets for ``scope:``
fields.
The metadata identifying each domain is itself a list containing one or two
entries. The first entry is the name of the domain. Note that if the name is a
-string then it can be combined accross functions and translation units. A
+string then it can be combined across functions and translation units. A
self-reference can be used to create globally unique domain names. A
descriptive string may optionally be provided as a second list entry.
The metadata identifying each scope is also itself a list containing two or
three entries. The first entry is the name of the scope. Note that if the name
-is a string then it can be combined accross functions and translation units. A
+is a string then it can be combined across functions and translation units. A
self-reference can be used to create globally unique scope names. A metadata
reference to the scope's domain is the second entry. A descriptive string may
optionally be provided as a third list entry.
!2 = !{ i8 0, i8 2, i8 3, i8 6 }
!3 = !{ i8 -2, i8 0, i8 3, i8 6 }
+'``unpredictable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``unpredictable`` metadata may be attached to any branch or switch
+instruction. It can be used to express the unpredictability of control
+flow. Similar to the llvm.expect intrinsic, it may be used to alter
+optimizations related to compare and branch instructions. The metadata
+is treated as a boolean value; if it exists, it signals that the branch
+or switch that it is attached to is completely unpredictable.
+
'``llvm.loop``'
^^^^^^^^^^^^^^^
The ``llvm.bitsets`` global metadata is used to implement
:doc:`bitsets <BitSets>`.
+'``invariant.group``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``invariant.group`` metadata may be attached to ``load``/``store`` instructions.
+The existence of the ``invariant.group`` metadata on the instruction tells
+the optimizer that every ``load`` and ``store`` to the same pointer operand
+within the same invariant group can be assumed to load or store the same
+value (but see the ``llvm.invariant.group.barrier`` intrinsic which affects
+when two pointers are considered the same).
+
+Examples:
+
+.. code-block:: llvm
+
+ @unknownPtr = external global i8
+ ...
+ %ptr = alloca i8
+ store i8 42, i8* %ptr, !invariant.group !0
+ call void @foo(i8* %ptr)
+
+ %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change
+ call void @foo(i8* %ptr)
+ %b = load i8, i8* %ptr, !invariant.group !1 ; Can't assume anything, because group changed
+
+ %newPtr = call i8* @getPointer(i8* %ptr)
+ %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr
+
+ %unknownValue = load i8, i8* @unknownPtr
+ store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42
+
+ call void @foo(i8* %ptr)
+ %newPtr2 = call i8* @llvm.invariant.group.barrier(i8* %ptr)
+ %d = load i8, i8* %newPtr2, !invariant.group !0 ; Can't step through invariant.group.barrier to get value of %ptr
+
+ ...
+ declare void @foo(i8*)
+ declare i8* @getPointer(i8*)
+ declare i8* @llvm.invariant.group.barrier(i8*)
+
+ !0 = !{!"magic ptr"}
+ !1 = !{!"other ptr"}
+
+
+
Module Flags Metadata
=====================
':ref:`resume <i_resume>`', ':ref:`catchpad <i_catchpad>`',
':ref:`catchendpad <i_catchendpad>`',
':ref:`catchret <i_catchret>`',
+':ref:`cleanupendpad <i_cleanupendpad>`',
':ref:`cleanupret <i_cleanupret>`',
':ref:`terminatepad <i_terminatepad>`',
and ':ref:`unreachable <i_unreachable>`'.
::
- <resultval> = catchpad
<resultty> [<args>*]
+ <resultval> = catchpad [<args>*]
to label <normal label> unwind label <exception label>
Overview:
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
+exception. Control is transfered to the ``exception`` label if the
``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
-function. The ``resultval`` has the type ``resultty``.
+portion of a ``try``/``catch`` sequence. The ``resultval`` has the type
+:ref:`token <t_token>` and is used to match the ``catchpad`` to
+corresponding :ref:`catchrets <i_catchret>`.
Arguments:
""""""""""
Semantics:
""""""""""
-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 ``catchpad`` 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.
+As with calling conventions, how the personality function results are
+represented in LLVM IR is target specific.
The ``catchpad`` instruction has several restrictions:
catch block.
- A basic block that is not a catch block may not include a
'``catchpad``' instruction.
+- A catch block which has another catch block as a predecessor may not have
+ any other predecessors.
- 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``.
+ ``ret`` without first executing a ``catchret`` that consumes the
+ ``catchpad`` or unwinding through its ``catchendpad``.
+- It is undefined behavior for control to transfer from a ``catchpad`` to
+ itself without first executing a ``catchret`` that consumes the
+ ``catchpad`` or unwinding through its ``catchendpad``.
Example:
""""""""
.. code-block:: llvm
;; A catch block which can catch an integer.
- %res = catchpad { i8*, i32 } [i8** @_ZTIi]
+ %tok = catchpad [i8** @_ZTIi]
to label %int.handler unwind label %terminate
.. _i_catchendpad:
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:`catchpad <i_catchpad>` instructions.
+with a chain of :ref:`catchpad <i_catchpad>` instructions; propagating an
+exception out of a catch handler is represented by unwinding through its
+``catchendpad``. Unwinding to the outer scope when a chain of catch handlers
+do not handle an exception is also represented by unwinding through their
+``catchendpad``.
The ``nextaction`` label indicates where control should transfer to if
none of the ``catchpad`` instructions are suitable for catching the
- A catch-end block must have a '``catchendpad``' instruction as its
first non-PHI instruction.
- There can be only one '``catchendpad``' instruction within the
- catch block.
+ catch-end block.
- A basic block that is not a catch-end block may not include a
'``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``.
+- It is undefined behavior to execute a ``catchendpad`` if none of the
+ '``catchpad``'s chained to it have been executed.
+- It is undefined behavior to execute a ``catchendpad`` twice without an
+ intervening execution of one or more of the '``catchpad``'s chained to it.
+- It is undefined behavior to execute a ``catchendpad`` if, after the most
+ recent execution of the normal successor edge of any ``catchpad`` chained
+ to it, some ``catchret`` consuming that ``catchpad`` has already been
+ executed.
+- It is undefined behavior to execute a ``catchendpad`` if, after the most
+ recent execution of the normal successor edge of any ``catchpad`` chained
+ to it, any other ``catchpad`` or ``cleanuppad`` has been executed but has
+ not had a corresponding
+ ``catchret``/``cleanupret``/``catchendpad``/``cleanupendpad`` executed.
Example:
""""""""
::
- catchret <type> <value> to label <normal>
+ catchret <value> to label <normal>
Overview:
"""""""""
Arguments:
""""""""""
-The '``catchret``' instruction requires one argument which specifies
-where control will transfer to next.
+The first argument to a '``catchret``' indicates which ``catchpad`` it
+exits. It must be a :ref:`catchpad <i_catchpad>`.
+The second argument to a '``catchret``' specifies where control will
+transfer to next.
Semantics:
""""""""""
Control then transfers to ``normal``.
It may be passed an optional, personality specific, value.
+It is undefined behavior to execute a ``catchret`` whose ``catchpad`` has
+not been executed.
+
+It is undefined behavior to execute a ``catchret`` if, after the most recent
+execution of its ``catchpad``, some ``catchret`` or ``catchendpad`` linked
+to the same ``catchpad`` has already been executed.
+
+It is undefined behavior to execute a ``catchret`` if, after the most recent
+execution of its ``catchpad``, any other ``catchpad`` or ``cleanuppad`` has
+been executed but has not had a corresponding
+``catchret``/``cleanupret``/``catchendpad``/``cleanupendpad`` executed.
+
Example:
""""""""
.. code-block:: llvm
- catchret label %continue
+ catchret %catch label %continue
+
+.. _i_cleanupendpad:
+
+'``cleanupendpad``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ cleanupendpad <value> unwind label <nextaction>
+ cleanupendpad <value> unwind to caller
+
+Overview:
+"""""""""
+
+The '``cleanupendpad``' 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 :ref:`cleanuppad <i_cleanuppad>` instructions; propagating an exception
+out of a cleanup is represented by unwinding through its ``cleanupendpad``.
+
+The ``nextaction`` label indicates where control should unwind to next, in the
+event that a cleanup is exited by means of an(other) exception being raised.
+
+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 '``cleanupendpad``' instruction requires one argument, which indicates
+which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_cleanuppad>`.
+It also has an optional successor, ``nextaction``, indicating where control
+should transfer to.
+
+Semantics:
+""""""""""
+
+When and exception propagates to a ``cleanupendpad``, control is transfered to
+``nextaction`` if it is present. If it is not present, control is transfered to
+the caller.
+
+The ``cleanupendpad`` instruction has several restrictions:
+
+- A cleanup-end block is a basic block which is the unwind destination of
+ an exceptional instruction.
+- A cleanup-end block must have a '``cleanupendpad``' instruction as its
+ first non-PHI instruction.
+- There can be only one '``cleanupendpad``' instruction within the
+ cleanup-end block.
+- A basic block that is not a cleanup-end block may not include a
+ '``cleanupendpad``' instruction.
+- It is undefined behavior to execute a ``cleanupendpad`` whose ``cleanuppad``
+ has not been executed.
+- It is undefined behavior to execute a ``cleanupendpad`` if, after the most
+ recent execution of its ``cleanuppad``, some ``cleanupret`` or ``cleanupendpad``
+ consuming the same ``cleanuppad`` has already been executed.
+- It is undefined behavior to execute a ``cleanupendpad`` if, after the most
+ recent execution of its ``cleanuppad``, any other ``cleanuppad`` or
+ ``catchpad`` has been executed but has not had a corresponding
+ ``cleanupret``/``catchret``/``cleanupendpad``/``catchendpad`` executed.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ cleanupendpad %cleanup unwind label %terminate
+ cleanupendpad %cleanup unwind to caller
.. _i_cleanupret:
::
- cleanupret <type> <value> unwind label <continue>
- cleanupret <type> <value> unwind to caller
+ cleanupret <value> unwind label <continue>
+ cleanupret <value> unwind to caller
Overview:
"""""""""
Arguments:
""""""""""
-The '``cleanupret``' instruction requires one argument, which must have the
-same type as the result of any '``cleanuppad``' instruction in the same
-function. It also has an optional successor, ``continue``.
+The '``cleanupret``' instruction requires one argument, which indicates
+which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_cleanuppad>`.
+It also has an optional successor, ``continue``.
Semantics:
""""""""""
:ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended.
It transfers control to ``continue`` or unwinds out of the function.
+It is undefined behavior to execute a ``cleanupret`` whose ``cleanuppad`` has
+not been executed.
+
+It is undefined behavior to execute a ``cleanupret`` if, after the most recent
+execution of its ``cleanuppad``, some ``cleanupret`` or ``cleanupendpad``
+consuming the same ``cleanuppad`` has already been executed.
+
+It is undefined behavior to execute a ``cleanupret`` if, after the most recent
+execution of its ``cleanuppad``, any other ``cleanuppad`` or ``catchpad`` has
+been executed but has not had a corresponding
+``cleanupret``/``catchret``/``cleanupendpad``/``catchendpad`` executed.
+
Example:
""""""""
.. code-block:: llvm
- cleanupret void unwind to caller
- cleanupret { i8*, i32 } %exn unwind label %continue
+ cleanupret %cleanup unwind to caller
+ cleanupret %cleanup unwind label %continue
.. _i_terminatepad:
::
- <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !nonnull !<index>][, !dereferenceable !<index>][, !dereferenceable_or_null !<index>]
- <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
+ <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !invariant.group !<index>][, !nonnull !<index>][, !dereferenceable !<index>][, !dereferenceable_or_null !<index>]
+ <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> [, !invariant.group !<index>]
!<index> = !{ i32 1 }
Overview:
but it does imply that once the location is known dereferenceable
its value is henceforth unchanging.
+The optional ``!invariant.group`` metadata must reference a single metadata name
+ ``<index>`` corresponding to a metadata node. See ``invariant.group`` metadata.
+
The optional ``!nonnull`` metadata must reference a single
metadata name ``<index>`` corresponding to a metadata node with no
entries. The existence of the ``!nonnull`` metadata on the
instruction tells the optimizer that the value loaded is known to
-never be null. This is analogous to the ''nonnull'' attribute
+never be null. This is analogous to the ``nonnull`` attribute
on parameters and return values. This metadata can only be applied
to loads of a pointer type.
::
- store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] ; yields void
- store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> ; yields void
+ store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.group !<index>] ; yields void
+ store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> [, !invariant.group !<index>] ; yields void
Overview:
"""""""""
instructions to save cache bandwidth, such as the MOVNT instruction on
x86.
+The optional ``!invariant.group`` metadata must reference a
+single metadata name ``<index>``. See ``invariant.group`` metadata.
+
Semantics:
""""""""""
Semantics:
""""""""""
-The '``fptrunc``' instruction truncates a ``value`` from a larger
+The '``fptrunc``' instruction casts 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.
+point <t_floating>` type. If the value cannot fit (i.e. overflows) within the
+destination type, ``ty2``, then the results are undefined. If the cast produces
+an inexact result, how rounding is performed (e.g. truncation, also known as
+round to zero) is undefined.
Example:
""""""""
::
- <resultval> = cleanuppad
<resultty> [<args>*]
+ <resultval> = cleanuppad [<args>*]
Overview:
"""""""""
The ``args`` correspond to whatever additional
information the :ref:`personality function <personalityfn>` requires to
execute the cleanup.
-The ``resultval`` has the type ``resultty``.
+The ``resultval`` has the type :ref:`token <t_token>` and is used to
+match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`
+and :ref:`cleanupendpads <i_cleanupendpad>`.
Arguments:
""""""""""
Semantics:
""""""""""
-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 ``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
``cleanuppad`` with the aid of the personality-specific arguments.
+As with calling conventions, how the personality function results are
+represented in LLVM IR is target specific.
The ``cleanuppad`` instruction has several restrictions:
cleanup block.
- A basic block that is not a cleanup block may not include a
'``cleanuppad``' instruction.
+- All '``cleanupret``'s and '``cleanupendpad``'s which consume a ``cleanuppad``
+ must have the same exceptional successor.
- 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``.
+ ``ret`` without first executing a ``cleanupret`` or ``cleanupendpad`` that
+ consumes the ``cleanuppad``.
+- It is undefined behavior for control to transfer from a ``cleanuppad`` to
+ itself without first executing a ``cleanupret`` or ``cleanupendpad`` that
+ consumes the ``cleanuppad``.
Example:
""""""""
.. code-block:: llvm
- %res = cleanuppad { i8*, i32 } [label %nextaction]
+ %tok = cleanuppad []
.. _intrinsics:
Semantics:
""""""""""
-The '``llvm.masked.scatter``' intrinsics is designed for writing selected vector elements to arbitrary memory addresses in a single IR operation. The operation may be conditional, when not all bits in the mask are switched on. It is useful for targets that support vector masked scatter and allows vectorizing basic blocks with data and control divergency. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
+The '``llvm.masked.scatter``' intrinsics is designed for writing selected vector elements to arbitrary memory addresses in a single IR operation. The operation may be conditional, when not all bits in the mask are switched on. It is useful for targets that support vector masked scatter and allows vectorizing basic blocks with data and control divergence. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
::
This intrinsic indicates that the memory is mutable again.
+'``llvm.invariant.group.barrier``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.invariant.group.barrier(i8* <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.invariant.group.barrier``' intrinsic can be used when an invariant
+established by invariant.group metadata no longer holds, to obtain a new pointer
+value that does not carry the invariant information.
+
+
+Arguments:
+""""""""""
+
+The ``llvm.invariant.group.barrier`` takes only one argument, which is
+the pointer to the memory for which the ``invariant.group`` no longer holds.
+
+Semantics:
+""""""""""
+
+Returns another pointer that aliases its argument but which is considered different
+for the purposes of ``load``/``store`` ``invariant.group`` metadata.
+
General Intrinsics
------------------
""""""""""
The first argument is a pointer to be tested. The second argument is a
-metadata string containing the name of a :doc:`bitset <BitSets>`.
+metadata object representing an identifier for a :doc:`bitset <BitSets>`.
Overview:
"""""""""
projects / oota-llvm.git / blobdiff