diff options
Diffstat (limited to 'llvm/docs/LangRef.rst')
| -rw-r--r-- | llvm/docs/LangRef.rst | 351 |
1 files changed, 350 insertions, 1 deletions
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index ca5c16c0f49..faa1d7c6c36 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -4727,7 +4727,11 @@ control flow, not values (the one exception being the 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>`', and ':ref:`unreachable <i_unreachable>`'. +':ref:`resume <i_resume>`', ':ref:`catchblock <i_catchblock>`', +':ref:`catchendblock <i_catchendblock>`', +':ref:`catchret <i_catchret>`', +':ref:`terminateblock <i_terminateblock>`', +and ':ref:`unreachable <i_unreachable>`'. .. _i_ret: @@ -5081,6 +5085,289 @@ Example: 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. +- 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 +the function it is located in. The +:ref:`personality function <personalityfn>` will look for an appropriate +catch block 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. + +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. + +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 and transfer control to +``normal``. + +Example: +"""""""" + +.. code-block:: llvm + + catchret unwind 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 the +:ref:`cleanupblock <i_cleanupblock>` it transfered control to has ended. +It transfers control to ``continue`` or unwinds out of the function. + +Example: +"""""""" + +.. code-block:: llvm + + cleanupret { i8*, i32 } %exn unwind label %continue + +.. _i_terminateblock: + +'``terminateblock``' Instruction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + terminateblock [<args>*] unwind label <exception label> + +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 attempts to transfer +control 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. + +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 +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 @@ -8029,6 +8316,68 @@ 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. +: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>`. + +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 |
