X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FLangRef.rst;h=5f8a3a5a4a9874f99b190283814d1cdb7860a98c;hb=4f229233ffc588a35e3738d3c358f2cf7a5da1d1;hp=103d876b3cef1dadc192632365841aac0f198ee0;hpb=7e54c38de03268a98f329069556b7bcf166c8f05;p=oota-llvm.git diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 103d876b3ce..5f8a3a5a4a9 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -1579,6 +1579,8 @@ caller's deoptimization state to the callee's deoptimization state is semantically equivalent to composing the caller's deoptimization continuation after the callee's deoptimization continuation. +.. _ob_funclet: + Funclet Operand Bundles ^^^^^^^^^^^^^^^^^^^^^^^ @@ -1588,6 +1590,18 @@ is within a particular funclet. There can be at most one ``"funclet"`` operand bundle attached to a call site and it must have exactly one bundle operand. +If any funclet EH pads have been "entered" but not "exited" (per the +`description in the EH doc\ `_), +it is undefined behavior to execute a ``call`` or ``invoke`` which: + +* does not have a ``"funclet"`` bundle and is not a ``call`` to a nounwind + intrinsic, or +* has a ``"funclet"`` bundle whose operand is not the most-recently-entered + not-yet-exited funclet EH pad. + +Similarly, if no funclet EH pads have been entered-but-not-yet-exited, +executing a ``call`` or ``invoke`` with a ``"funclet"`` bundle is undefined behavior. + .. _moduleasm: Module-Level Inline Assembly @@ -5404,10 +5418,12 @@ The ``parent`` argument is the token of the funclet that contains the ``catchswitch`` instruction. If the ``catchswitch`` is not inside a funclet, this operand may be the token ``none``. -The ``default`` argument is the label of another basic block beginning with a -"pad" instruction, one of ``cleanuppad`` or ``catchswitch``. +The ``default`` argument is the label of another basic block beginning with +either a ``cleanuppad`` or ``catchswitch`` instruction. This unwind destination +must be a legal target with respect to the ``parent`` links, as described in +the `exception handling documentation\ `_. -The ``handlers`` are a list of successor blocks that each begin with a +The ``handlers`` are a nonempty list of successor blocks that each begin with a :ref:`catchpad ` instruction. Semantics: @@ -5431,82 +5447,6 @@ Example: dispatch2: %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup -.. _i_catchpad: - -'``catchpad``' Instruction -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: -""""""" - -:: - - = catchpad within [*] - -Overview: -""""""""" - -The '``catchpad``' instruction is used by `LLVM's exception handling -system `_ to specify that a basic block -begins a catch handler --- one where a personality routine attempts to transfer -control to catch an exception. - -Arguments: -"""""""""" - -The ``catchswitch`` operand must always be a token produced by a -:ref:`catchswitch ` instruction in a predecessor block. This -ensures that each ``catchpad`` has exactly one predecessor block, and it always -terminates in a ``catchswitch``. - -The ``args`` correspond to whatever information the personality routine -requires to know if this is an appropriate handler for the exception. Control -will transfer to the ``catchpad`` if this is the first appropriate handler for -the exception. - -The ``resultval`` has the type :ref:`token ` and is used to match the -``catchpad`` to corresponding :ref:`catchrets ` and other nested EH -pads. - -Semantics: -"""""""""" - -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, control will -not reach the ``catchpad`` instruction. The representation of ``args`` is -entirely target and personality function-specific. - -Like the :ref:`landingpad ` instruction, the ``catchpad`` -instruction must be the first non-phi of its parent basic block. - -The meaning of the tokens produced and consumed by ``catchpad`` and other "pad" -instructions is described in the -`Windows exception handling documentation `. - -Executing a ``catchpad`` instruction constitutes "entering" that pad. -The pad may then be "exited" in one of three ways: - -1) explicitly via a ``catchret`` that consumes it. Executing such a ``catchret`` - is undefined behavior if any descendant pads have been entered but not yet - exited. -2) implicitly via a call (which unwinds all the way to the current function's caller), - or via a ``catchswitch`` or a ``cleanupret`` that unwinds to caller. -3) implicitly via an unwind edge whose destination EH pad isn't a descendant of - the ``catchpad``. When the ``catchpad`` is exited in this manner, it is - undefined behavior if the destination EH pad has a parent which is not an - ancestor of the ``catchpad`` being exited. - -Example: -"""""""" - -.. code-block:: llvm - - dispatch: - %cs = catchswitch within none [label %handler0] unwind to caller - ;; A catch block which can catch an integer. - handler0: - %tok = catchpad within %cs [i8** @_ZTIi] - .. _i_catchret: '``catchret``' Instruction @@ -5543,11 +5483,10 @@ unwinding was interrupted with a :ref:`catchpad ` instruction. The code to, for example, destroy the active exception. Control then transfers to ``normal``. -The ``token`` argument must be a token produced by a dominating ``catchpad`` -instruction. The ``catchret`` destroys the physical frame established by -``catchpad``, so executing multiple returns on the same token without -re-executing the ``catchpad`` will result in undefined behavior. -See :ref:`catchpad ` for more details. +The ``token`` argument must be a token produced by a ``catchpad`` instruction. +If the specified ``catchpad`` is not the most-recently-entered not-yet-exited +funclet pad (as described in the `EH documentation\ `_), +the ``catchret``'s behavior is undefined. Example: """""""" @@ -5581,7 +5520,15 @@ Arguments: The '``cleanupret``' instruction requires one argument, which indicates which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad `. -It also has an optional successor, ``continue``. +If the specified ``cleanuppad`` is not the most-recently-entered not-yet-exited +funclet pad (as described in the `EH documentation\ `_), +the ``cleanupret``'s behavior is undefined. + +The '``cleanupret``' instruction also has an optional successor, ``continue``, +which must be the label of another basic block beginning with either a +``cleanuppad`` or ``catchswitch`` instruction. This unwind destination must +be a legal target with respect to the ``parent`` links, as described in the +`exception handling documentation\ `_. Semantics: """""""""" @@ -5591,13 +5538,6 @@ The '``cleanupret``' instruction indicates to the :ref:`cleanuppad ` it transferred control to has ended. It transfers control to ``continue`` or unwinds out of the function. -The unwind destination ``continue``, if present, must be an EH pad -whose parent is either ``none`` or an ancestor of the ``cleanuppad`` -being returned from. This constitutes an exceptional exit from all -ancestors of the completed ``cleanuppad``, up to but not including -the parent of ``continue``. -See :ref:`cleanuppad ` for more details. - Example: """""""" @@ -6996,7 +6936,7 @@ name ```` corresponding to a metadata node with one ``i32`` entry of value 1. The existence of the ``!nontemporal`` metadata on the instruction tells the optimizer and code generator that this load is not expected to be reused in the cache. The code generator may select special -instructions to save cache bandwidth, such as the MOVNT instruction on +instructions to save cache bandwidth, such as the ``MOVNT`` instruction on x86. The optional ``!invariant.group`` metadata must reference a @@ -8590,6 +8530,74 @@ Example: catch i8** @_ZTIi filter [1 x i8**] [@_ZTId] +.. _i_catchpad: + +'``catchpad``' Instruction +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + = catchpad within [*] + +Overview: +""""""""" + +The '``catchpad``' instruction is used by `LLVM's exception handling +system `_ to specify that a basic block +begins a catch handler --- one where a personality routine attempts to transfer +control to catch an exception. + +Arguments: +"""""""""" + +The ``catchswitch`` operand must always be a token produced by a +:ref:`catchswitch ` instruction in a predecessor block. This +ensures that each ``catchpad`` has exactly one predecessor block, and it always +terminates in a ``catchswitch``. + +The ``args`` correspond to whatever information the personality routine +requires to know if this is an appropriate handler for the exception. Control +will transfer to the ``catchpad`` if this is the first appropriate handler for +the exception. + +The ``resultval`` has the type :ref:`token ` and is used to match the +``catchpad`` to corresponding :ref:`catchrets ` and other nested EH +pads. + +Semantics: +"""""""""" + +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, control will +not reach the ``catchpad`` instruction. The representation of ``args`` is +entirely target and personality function-specific. + +Like the :ref:`landingpad ` instruction, the ``catchpad`` +instruction must be the first non-phi of its parent basic block. + +The meaning of the tokens produced and consumed by ``catchpad`` and other "pad" +instructions is described in the +`Windows exception handling documentation\ `_. + +When a ``catchpad`` has been "entered" but not yet "exited" (as +described in the `EH documentation\ `_), +it is undefined behavior to execute a :ref:`call ` or :ref:`invoke ` +that does not carry an appropriate :ref:`"funclet" bundle `. + +Example: +"""""""" + +.. code-block:: llvm + + dispatch: + %cs = catchswitch within none [label %handler0] unwind to caller + ;; A catch block which can catch an integer. + handler0: + %tok = catchpad within %cs [i8** @_ZTIi] + .. _i_cleanuppad: '``cleanuppad``' Instruction @@ -8644,22 +8652,10 @@ The ``cleanuppad`` instruction has several restrictions: - A basic block that is not a cleanup block may not include a '``cleanuppad``' instruction. -Executing a ``cleanuppad`` instruction constitutes "entering" that pad. -The pad may then be "exited" in one of three ways: - -1) explicitly via a ``cleanupret`` that consumes it. Executing such a ``cleanupret`` - is undefined behavior if any descendant pads have been entered but not yet - exited. -2) implicitly via a call (which unwinds all the way to the current function's caller), - or via a ``catchswitch`` or a ``cleanupret`` that unwinds to caller. -3) implicitly via an unwind edge whose destination EH pad isn't a descendant of - the ``cleanuppad``. When the ``cleanuppad`` is exited in this manner, it is - undefined behavior if the destination EH pad has a parent which is not an - ancestor of the ``cleanuppad`` being exited. - -It is undefined behavior for the ``cleanuppad`` to exit via an unwind edge which -does not transitively unwind to the same destination as a constituent -``cleanupret``. +When a ``cleanuppad`` has been "entered" but not yet "exited" (as +described in the `EH documentation\ `_), +it is undefined behavior to execute a :ref:`call ` or :ref:`invoke ` +that does not carry an appropriate :ref:`"funclet" bundle `. Example: """"""""