add unpredictable metadata type for control flow

[oota-llvm.git] / docs / LangRef.rst

diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index ef5913b78f3858c56d63e7c7870eb9fc8135ce13..3c29e9a061849a8314290705fc758fb007c97365 100644 (file)
--- a/docs/LangRef.rst
+++ b/docs/LangRef.rst
@@ -4163,6 +4163,16 @@ Examples:
     !2 = !{ i8 0, i8 2, i8 3, i8 6 }
     !3 = !{ i8 -2, i8 0, i8 3, i8 6 }
 
     !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``'
 ^^^^^^^^^^^^^^^
 
 '``llvm.loop``'
 ^^^^^^^^^^^^^^^
 


@@ -5138,7 +5148,7 @@ Syntax:
 
 ::
 
 
 ::
 

-      <resultval> = catchpad <resultty> [<args>*]
+      <resultval> = catchpad [<args>*]

           to label <normal label> unwind label <exception label>
 
 Overview:
           to label <normal label> unwind label <exception label>
 
 Overview:


@@ -5153,9 +5163,9 @@ routine requires to know if this is an appropriate place to catch the
 exception. Control is tranfered 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``
 exception. Control is tranfered 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:
 """"""""""
 
 Arguments:
 """"""""""


@@ -5170,15 +5180,11 @@ label to transfer control to if it doesn't.
 Semantics:
 """"""""""
 
 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.
 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:
 
 
 The ``catchpad`` instruction has several restrictions:
 


@@ -5192,11 +5198,14 @@ The ``catchpad`` instruction has several restrictions:
    catch block.
 -  A basic block that is not a catch block may not include a
    '``catchpad``' instruction.
    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
 -  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:
 """"""""
 
 Example:
 """"""""


@@ -5204,7 +5213,7 @@ Example:
 .. code-block:: llvm
 
       ;; A catch block which can catch an integer.
 .. 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:
         to label %int.handler unwind label %terminate
 
 .. _i_catchendpad:


@@ -5264,7 +5273,8 @@ The ``catchendpad`` instruction has several restrictions:
    '``catchendpad``' instruction.
 -  Exactly one catch block may unwind to a ``catchendpad``.
 -  The unwind target of invokes between a ``catchpad`` and 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``.
+   corresponding ``catchret`` must be its ``catchendpad`` or
+   an inner EH pad.

 
 Example:
 """"""""
 
 Example:
 """"""""


@@ -5284,7 +5294,7 @@ Syntax:
 
 ::
 
 
 ::
 

-      catchret label <normal>
+      catchret <value> to label <normal>

 
 Overview:
 """""""""
 
 Overview:
 """""""""


@@ -5296,8 +5306,10 @@ single successor.
 Arguments:
 """"""""""
 
 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:
 """"""""""
 
 Semantics:
 """"""""""


@@ -5308,13 +5320,22 @@ whose unwinding was interrupted with a
 The :ref:`personality function <personalityfn>` gets a chance to execute
 arbitrary code to, for example, run a C++ destructor.
 Control then transfers to ``normal``.
 The :ref:`personality function <personalityfn>` gets a chance to execute
 arbitrary code to, for example, run a C++ destructor.
 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 any ``catchpad`` or
+``cleanuppad`` has been executed, without subsequently executing a
+corresponding ``catchret``/``cleanupret`` or unwinding out of the inner
+pad, following the most recent execution of the ``catchret``'s corresponding
+``catchpad``.
+

 
 Example:
 """"""""
 
 .. code-block:: llvm
 
 
 Example:
 """"""""
 
 .. code-block:: llvm
 

-      catchret label %continue
+      catchret %catch label %continue

 
 .. _i_cleanupret:
 
 
 .. _i_cleanupret:
 


@@ -5326,8 +5347,8 @@ Syntax:
 
 ::
 
 
 ::
 

-      cleanupret <type> <value> unwind label <continue>
-      cleanupret <type> <value> unwind to caller
+      cleanupret <value> unwind label <continue>
+      cleanupret <value> unwind to caller

 
 Overview:
 """""""""
 
 Overview:
 """""""""


@@ -5339,9 +5360,9 @@ an optional successor.
 Arguments:
 """"""""""
 
 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:
 """"""""""
 
 Semantics:
 """"""""""


@@ -5350,14 +5371,21 @@ The '``cleanupret``' instruction indicates to the
 :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.
 :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.

+It is undefined behavior to execute a ``cleanupret`` whose ``cleanuppad`` has
+not been executed.
+It is undefined behavior to execute a ``cleanupret`` if any ``catchpad`` or
+``cleanuppad`` has been executed, without subsequently executing a
+corresponding ``catchret``/``cleanupret`` or unwinding out of the inner pad,
+following the most recent execution of the ``cleanupret``'s corresponding
+``cleanuppad``.

 
 Example:
 """"""""
 
 .. code-block:: llvm
 
 
 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:
 
 
 .. _i_terminatepad:
 


@@ -8390,7 +8418,7 @@ Syntax:
 
 ::
 
 
 ::
 

-      <resultval> = cleanuppad <resultty> [<args>*]
+      <resultval> = cleanuppad [<args>*]

 
 Overview:
 """""""""
 
 Overview:
 """""""""


@@ -8402,7 +8430,8 @@ transfer control to run cleanup actions.
 The ``args`` correspond to whatever additional
 information the :ref:`personality function <personalityfn>` requires to
 execute the cleanup.
 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>`.

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


@@ -8414,9 +8443,8 @@ Semantics:
 """"""""""
 
 The '``cleanuppad``' 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 ``cleanuppad`` instruction. As with
-calling conventions, how the personality function results are
+:ref:`personality function <personalityfn>` upon re-entry to the function.
+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,
 represented in LLVM IR is target specific.
 
 When the call stack is being unwound due to an exception being thrown,


@@ -8433,18 +8461,21 @@ The ``cleanuppad`` instruction has several restrictions:
    cleanup block.
 -  A basic block that is not a cleanup block may not include a
    '``cleanuppad``' instruction.
    cleanup block.
 -  A basic block that is not a cleanup block may not include a
    '``cleanuppad``' instruction.

+-  All '``cleanupret``'s which exit a ``cleanuppad`` must have the same
+   exceptional successor.

 -  It is undefined behavior for control to transfer from a ``cleanuppad`` to a
 -  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`` that consumes the
+   ``cleanuppad`` or unwinding out of the ``cleanuppad``.
+-  It is undefined behavior for control to transfer from a ``cleanuppad`` to
+   itself without first executing a ``cleanupret`` that consumes the
+   ``cleanuppad`` or unwinding out of the ``cleanuppad``.

 
 Example:
 """"""""
 
 .. code-block:: llvm
 
 
 Example:
 """"""""
 
 .. code-block:: llvm
 

-      %res = cleanuppad { i8*, i32 } [label %nextaction]
+      %tok = cleanuppad []

 
 .. _intrinsics:
 
 
 .. _intrinsics:
 


@@ -10741,11 +10772,11 @@ This is an overloaded intrinsic. The loaded data is a vector of any integer bit
 Overview:
 """""""""
 
 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.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.
+The ``llvm.sabsdiff`` intrinsic returns a vector result of the absolute difference of
+the two operands, treating them both as signed integers.

 
 .. note::
 
 
 .. note::