Sphinxify the exception handling doc.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@159254 91177308-0d34-0410-b5e6-96231b3b80d8
author: Bill Wendling <isanbard@gmail.com> 2012-06-27 07:20:57 +0000
committer: Bill Wendling <isanbard@gmail.com> 2012-06-27 07:20:57 +0000
commit: 7d85f87acb4d46cfd315a08f6f64b23818eb47e4 (patch)
tree: fb88c07cd4a4adc6c3009dc7213042e9eca95318 /docs
parent: e246b52d2b02753a0064fb7e984148fff55d2872 (diff)
download: external_llvm-7d85f87acb4d46cfd315a08f6f64b23818eb47e4.zip
external_llvm-7d85f87acb4d46cfd315a08f6f64b23818eb47e4.tar.gz
external_llvm-7d85f87acb4d46cfd315a08f6f64b23818eb47e4.tar.bz2
3 files changed, 369 insertions, 564 deletions
diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html
deleted file mode 100644
index ae0fa51..0000000
--- a/docs/ExceptionHandling.html
+++ /dev/null
@@ -1,563 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
-                      "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-  <title>Exception Handling in LLVM</title>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-  <meta name="description"
-        content="Exception Handling in LLVM.">
-  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
-</head>
-
-<body>
-
-<h1>Exception Handling in LLVM</h1>
-
-<table class="layout" style="width:100%">
-  <tr class="layout">
-    <td class="left">
-<ul>
-  <li><a href="#introduction">Introduction</a>
-  <ol>
-    <li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li>
-    <li><a href="#sjlj">Setjmp/Longjmp Exception Handling</a></li>
-    <li><a href="#overview">Overview</a></li>
-  </ol></li>
-  <li><a href="#codegen">LLVM Code Generation</a>
-  <ol>
-    <li><a href="#throw">Throw</a></li>
-    <li><a href="#try_catch">Try/Catch</a></li>
-    <li><a href="#cleanups">Cleanups</a></li>
-    <li><a href="#throw_filters">Throw Filters</a></li>
-    <li><a href="#restrictions">Restrictions</a></li>
-  </ol></li>
-  <li><a href="#format_common_intrinsics">Exception Handling Intrinsics</a>
-  <ol>
-  	<li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li>
-  	<li><a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a></li>
-  	<li><a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a></li>
-  	<li><a href="#llvm_eh_sjlj_lsda"><tt>llvm.eh.sjlj.lsda</tt></a></li>
-  	<li><a href="#llvm_eh_sjlj_callsite"><tt>llvm.eh.sjlj.callsite</tt></a></li>
-  </ol></li>
-  <li><a href="#asm">Asm Table Formats</a>
-  <ol>
-    <li><a href="#unwind_tables">Exception Handling Frame</a></li>
-    <li><a href="#exception_tables">Exception Tables</a></li>
-  </ol></li>
-</ul>
-</td>
-</tr></table>
-
-<div class="doc_author">
-  <p>Written by the <a href="http://llvm.org/">LLVM Team</a></p>
-</div>
-
-
-<!-- *********************************************************************** -->
-<h2><a name="introduction">Introduction</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>This document is the central repository for all information pertaining to
-   exception handling in LLVM.  It describes the format that LLVM exception
-   handling information takes, which is useful for those interested in creating
-   front-ends or dealing directly with the information.  Further, this document
-   provides specific examples of what exception handling information is used for
-   in C and C++.</p>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="itanium">Itanium ABI Zero-cost Exception Handling</a>
-</h3>
-
-<div>
-
-<p>Exception handling for most programming languages is designed to recover from
-   conditions that rarely occur during general use of an application.  To that
-   end, exception handling should not interfere with the main flow of an
-   application's algorithm by performing checkpointing tasks, such as saving the
-   current pc or register state.</p>
-
-<p>The Itanium ABI Exception Handling Specification defines a methodology for
-   providing outlying data in the form of exception tables without inlining
-   speculative exception handling code in the flow of an application's main
-   algorithm.  Thus, the specification is said to add "zero-cost" to the normal
-   execution of an application.</p>
-
-<p>A more complete description of the Itanium ABI exception handling runtime
-   support of can be found at
-   <a href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI:
-   Exception Handling</a>. A description of the exception frame format can be
-   found at
-   <a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception
-   Frames</a>, with details of the DWARF 4 specification at
-   <a href="http://dwarfstd.org/Dwarf4Std.php">DWARF 4 Standard</a>.
-   A description for the C++ exception table formats can be found at
-   <a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling
-   Tables</a>.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="sjlj">Setjmp/Longjmp Exception Handling</a>
-</h3>
-
-<div>
-
-<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
-   <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and
-   <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> to
-   handle control flow for exception handling.</p>
-
-<p>For each function which does exception processing &mdash; be
-   it <tt>try</tt>/<tt>catch</tt> blocks or cleanups &mdash; that function
-   registers itself on a global frame list. When exceptions are unwinding, the
-   runtime uses this list to identify which functions need processing.<p>
-
-<p>Landing pad selection is encoded in the call site entry of the function
-   context. The runtime returns to the function via
-   <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>, where
-   a switch table transfers control to the appropriate landing pad based on
-   the index stored in the function context.</p>
-
-<p>In contrast to DWARF exception handling, which encodes exception regions
-   and frame information in out-of-line tables, SJLJ exception handling
-   builds and removes the unwind frame context at runtime. This results in
-   faster exception handling at the expense of slower execution when no
-   exceptions are thrown. As exceptions are, by their nature, intended for
-   uncommon code paths, DWARF exception handling is generally preferred to
-   SJLJ.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="overview">Overview</a>
-</h3>
-
-<div>
-
-<p>When an exception is thrown in LLVM code, the runtime does its best to find a
-   handler suited to processing the circumstance.</p>
-
-<p>The runtime first attempts to find an <i>exception frame</i> corresponding to
-   the function where the exception was thrown.  If the programming language
-   supports exception handling (e.g. C++), the exception frame contains a
-   reference to an exception table describing how to process the exception.  If
-   the language does not support exception handling (e.g. C), or if the
-   exception needs to be forwarded to a prior activation, the exception frame
-   contains information about how to unwind the current activation and restore
-   the state of the prior activation.  This process is repeated until the
-   exception is handled. If the exception is not handled and no activations
-   remain, then the application is terminated with an appropriate error
-   message.</p>
-
-<p>Because different programming languages have different behaviors when
-   handling exceptions, the exception handling ABI provides a mechanism for
-   supplying <i>personalities</i>. An exception handling personality is defined
-   by way of a <i>personality function</i> (e.g. <tt>__gxx_personality_v0</tt>
-   in C++), which receives the context of the exception, an <i>exception
-   structure</i> containing the exception object type and value, and a reference
-   to the exception table for the current function.  The personality function
-   for the current compile unit is specified in a <i>common exception
-   frame</i>.</p>
-
-<p>The organization of an exception table is language dependent. For C++, an
-   exception table is organized as a series of code ranges defining what to do
-   if an exception occurs in that range. Typically, the information associated
-   with a range defines which types of exception objects (using C++ <i>type
-   info</i>) that are handled in that range, and an associated action that
-   should take place. Actions typically pass control to a <i>landing
-   pad</i>.</p>
-
-<p>A landing pad corresponds roughly to the code found in the <tt>catch</tt>
-   portion of a <tt>try</tt>/<tt>catch</tt> sequence. When execution resumes at
-   a landing pad, it receives an <i>exception structure</i> and a
-   <i>selector value</i> corresponding to the <i>type</i> of exception
-   thrown. The selector is then used to determine which <i>catch</i> should
-   actually process the exception.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h2>
-  <a name="codegen">LLVM Code Generation</a>
-</h2>
-
-<div>
-
-<p>From a C++ developer's perspective, exceptions are defined in terms of the
-   <tt>throw</tt> and <tt>try</tt>/<tt>catch</tt> statements. In this section
-   we will describe the implementation of LLVM exception handling in terms of
-   C++ examples.</p>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="throw">Throw</a>
-</h3>
-
-<div>
-
-<p>Languages that support exception handling typically provide a <tt>throw</tt>
-   operation to initiate the exception process. Internally, a <tt>throw</tt>
-   operation breaks down into two steps.</p>
-
-<ol>
-  <li>A request is made to allocate exception space for an exception structure.
-      This structure needs to survive beyond the current activation. This
-      structure will contain the type and value of the object being thrown.</li>
-
-  <li>A call is made to the runtime to raise the exception, passing the
-      exception structure as an argument.</li>
-</ol>
-
-<p>In C++, the allocation of the exception structure is done by the
-   <tt>__cxa_allocate_exception</tt> runtime function. The exception raising is
-   handled by <tt>__cxa_throw</tt>. The type of the exception is represented
-   using a C++ RTTI structure.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="try_catch">Try/Catch</a>
-</h3>
-
-<div>
-
-<p>A call within the scope of a <i>try</i> statement can potentially raise an
-   exception. In those circumstances, the LLVM C++ front-end replaces the call
-   with an <tt>invoke</tt> instruction. Unlike a call, the <tt>invoke</tt> has
-   two potential continuation points:</p>
-
-<ol>
-  <li>where to continue when the call succeeds as per normal, and</li>
-
-  <li>where to continue if the call raises an exception, either by a throw or
-      the unwinding of a throw</li>
-</ol>
-
-<p>The term used to define a the place where an <tt>invoke</tt> continues after
-   an exception is called a <i>landing pad</i>. LLVM landing pads are
-   conceptually alternative function entry points where an exception structure
-   reference and a type info index are passed in as arguments. The landing pad
-   saves the exception structure reference and then proceeds to select the catch
-   block that corresponds to the type info of the exception object.</p>
-
-<p>The LLVM <a href="LangRef.html#i_landingpad"><tt>landingpad</tt>
-   instruction</a> is used to convey information about the landing pad to the
-   back end. For C++, the <tt>landingpad</tt> instruction returns a pointer and
-   integer pair corresponding to the pointer to the <i>exception structure</i>
-   and the <i>selector value</i> respectively.</p>
-
-<p>The <tt>landingpad</tt> instruction takes a reference to the personality
-   function to be used for this <tt>try</tt>/<tt>catch</tt> sequence. The
-   remainder of the instruction is a list of <i>cleanup</i>, <i>catch</i>,
-   and <i>filter</i> clauses. The exception is tested against the clauses
-   sequentially from first to last. The selector value is a positive number if
-   the exception matched a type info, a negative number if it matched a filter,
-   and zero if it matched a cleanup. If nothing is matched, the behavior of
-   the program is <a href="#restrictions">undefined</a>. If a type info matched,
-   then the selector value is the index of the type info in the exception table,
-   which can be obtained using the
-   <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p>
-
-<p>Once the landing pad has the type info selector, the code branches to the
-   code for the first catch. The catch then checks the value of the type info
-   selector against the index of type info for that catch.  Since the type info
-   index is not known until all the type infos have been gathered in the
-   backend, the catch code must call the
-   <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic to
-   determine the index for a given type info. If the catch fails to match the
-   selector then control is passed on to the next catch.</p>
-
-<p>Finally, the entry and exit of catch code is bracketed with calls to
-   <tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.</p>
-
-<ul>
-  <li><tt>__cxa_begin_catch</tt> takes an exception structure reference as an
-      argument and returns the value of the exception object.</li>
-
-  <li><tt>__cxa_end_catch</tt> takes no arguments. This function:<br><br>
-    <ol>
-      <li>Locates the most recently caught exception and decrements its handler
-          count,</li>
-      <li>Removes the exception from the <i>caught</i> stack if the handler
-          count goes to zero, and</li>
-      <li>Destroys the exception if the handler count goes to zero and the
-          exception was not re-thrown by throw.</li>
-    </ol>
-    <p><b>Note:</b> a rethrow from within the catch may replace this call with
-       a <tt>__cxa_rethrow</tt>.</p></li>
-</ul>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="cleanups">Cleanups</a>
-</h3>
-
-<div>
-
-<p>A cleanup is extra code which needs to be run as part of unwinding a scope.
-   C++ destructors are a typical example, but other languages and language
-   extensions provide a variety of different kinds of cleanups. In general, a
-   landing pad may need to run arbitrary amounts of cleanup code before actually
-   entering a catch block. To indicate the presence of cleanups, a
-   <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a>
-   should have a <i>cleanup</i> clause. Otherwise, the unwinder will not stop at
-   the landing pad if there are no catches or filters that require it to.</p>
-
-<p><b>Note:</b> Do not allow a new exception to propagate out of the execution
-   of a cleanup. This can corrupt the internal state of the unwinder.
-   Different languages describe different high-level semantics for these
-   situations: for example, C++ requires that the process be terminated, whereas
-   Ada cancels both exceptions and throws a third.</p>
-
-<p>When all cleanups are finished, if the exception is not handled by the
-   current function, resume unwinding by calling the
-   <a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a>, passing in
-   the result of the <tt>landingpad</tt> instruction for the original landing
-   pad.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="throw_filters">Throw Filters</a>
-</h3>
-
-<div>
-
-<p>C++ allows the specification of which exception types may be thrown from a
-   function. To represent this, a top level landing pad may exist to filter out
-   invalid types. To express this in LLVM code the
-   <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> will
-   have a filter clause. The clause consists of an array of type infos.
-   <tt>landingpad</tt> will return a negative value if the exception does not
-   match any of the type infos. If no match is found then a call
-   to <tt>__cxa_call_unexpected</tt> should be made, otherwise
-   <tt>_Unwind_Resume</tt>.  Each of these functions requires a reference to the
-   exception structure.  Note that the most general form of a
-   <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> can
-   have any number of catch, cleanup, and filter clauses (though having more
-   than one cleanup is pointless). The LLVM C++ front-end can generate such
-   <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instructions</a> due
-   to inlining creating nested exception handling scopes.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="restrictions">Restrictions</a>
-</h3>
-
-<div>
-
-<p>The unwinder delegates the decision of whether to stop in a call frame to
-   that call frame's language-specific personality function. Not all unwinders
-   guarantee that they will stop to perform cleanups. For example, the GNU C++
-   unwinder doesn't do so unless the exception is actually caught somewhere
-   further up the stack.</p>
-
-<p>In order for inlining to behave correctly, landing pads must be prepared to
-   handle selector results that they did not originally advertise. Suppose that
-   a function catches exceptions of type <tt>A</tt>, and it's inlined into a
-   function that catches exceptions of type <tt>B</tt>. The inliner will update
-   the <tt>landingpad</tt> instruction for the inlined landing pad to include
-   the fact that <tt>B</tt> is also caught. If that landing pad assumes that it
-   will only be entered to catch an <tt>A</tt>, it's in for a rude awakening.
-   Consequently, landing pads must test for the selector results they understand
-   and then resume exception propagation with the
-   <a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a> if none of
-   the conditions match.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h2>
-  <a name="format_common_intrinsics">Exception Handling Intrinsics</a>
-</h2>
-
-<div>
-
-<p>In addition to the
-   <a href="LangRef.html#i_landingpad"><tt>landingpad</tt></a> and
-   <a href="LangRef.html#i_resume"><tt>resume</tt></a> instructions, LLVM uses
-   several intrinsic functions (name prefixed with <i><tt>llvm.eh</tt></i>) to
-   provide exception handling information at various points in generated
-   code.</p>
-
-<!-- ======================================================================= -->
-<h4>
-  <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a>
-</h4>
-
-<div>
-
-<pre>
-  i32 @llvm.eh.typeid.for(i8* %type_info)
-</pre>
-
-<p>This intrinsic returns the type info index in the exception table of the
-   current function.  This value can be used to compare against the result
-   of <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a>.
-   The single argument is a reference to a type info.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4>
-  <a name="llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>
-</h4>
-
-<div>
-
-<pre>
-  i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
-</pre>
-
-<p>For SJLJ based exception handling, this intrinsic forces register saving for
-   the current function and stores the address of the following instruction for
-   use as a destination address
-   by <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>. The
-   buffer format and the overall functioning of this intrinsic is compatible
-   with the GCC <tt>__builtin_setjmp</tt> implementation allowing code built
-   with the clang and GCC to interoperate.</p>
-
-<p>The single parameter is a pointer to a five word buffer in which the calling
-   context is saved. The front end places the frame pointer in the first word,
-   and the target implementation of this intrinsic should place the destination
-   address for a
-   <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> in the
-   second word. The following three words are available for use in a
-   target-specific manner.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4>
-  <a name="llvm_eh_sjlj_longjmp">llvm.eh.sjlj.longjmp</a>
-</h4>
-
-<div>
-
-<pre>
-  void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
-</pre>
-
-<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.longjmp</tt>
-   intrinsic is used to implement <tt>__builtin_longjmp()</tt>. The single
-   parameter is a pointer to a buffer populated
-   by <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a>. The frame
-   pointer and stack pointer are restored from the buffer, then control is
-   transferred to the destination address.</p>
-
-</div>
-<!-- ======================================================================= -->
-<h4>
-  <a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>
-</h4>
-
-<div>
-
-<pre>
-  i8* @llvm.eh.sjlj.lsda()
-</pre>
-
-<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.lsda</tt> intrinsic
-   returns the address of the Language Specific Data Area (LSDA) for the current
-   function. The SJLJ front-end code stores this address in the exception
-   handling function context for use by the runtime.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h4>
-  <a name="llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>
-</h4>
-
-<div>
-
-<pre>
-  void @llvm.eh.sjlj.callsite(i32 %call_site_num)
-</pre>
-
-<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.callsite</tt>
-   intrinsic identifies the callsite value associated with the
-   following <tt>invoke</tt> instruction. This is used to ensure that landing
-   pad entries in the LSDA are generated in matching order.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h2>
-  <a name="asm">Asm Table Formats</a>
-</h2>
-
-<div>
-
-<p>There are two tables that are used by the exception handling runtime to
-   determine which actions should be taken when an exception is thrown.</p>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="unwind_tables">Exception Handling Frame</a>
-</h3>
-
-<div>
-
-<p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind
-   frame used by DWARF debug info. The frame contains all the information
-   necessary to tear down the current frame and restore the state of the prior
-   frame. There is an exception handling frame for each function in a compile
-   unit, plus a common exception handling frame that defines information common
-   to all functions in the unit.</p>
-
-<!-- Todo - Table details here. -->
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-  <a name="exception_tables">Exception Tables</a>
-</h3>
-
-<div>
-
-<p>An exception table contains information about what actions to take when an
-   exception is thrown in a particular part of a function's code. There is one
-   exception table per function, except leaf functions and functions that have
-   calls only to non-throwing functions. They do not need an exception
-   table.</p>
-
-<!-- Todo - Table details here. -->
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-
-<hr>
-<address>
-  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
-  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
-  <a href="http://validator.w3.org/check/referer"><img
-  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
-
-  <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
-  Last modified: $Date$
-</address>
-
-</body>
-</html>
diff --git a/docs/ExceptionHandling.rst b/docs/ExceptionHandling.rst
new file mode 100644
index 0000000..190f182
--- /dev/null
+++ b/docs/ExceptionHandling.rst
@@ -0,0 +1,367 @@
+.. _exception_handling:
+
+==========================
+Exception Handling in LLVM
+==========================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document is the central repository for all information pertaining to
+exception handling in LLVM.  It describes the format that LLVM exception
+handling information takes, which is useful for those interested in creating
+front-ends or dealing directly with the information.  Further, this document
+provides specific examples of what exception handling information is used for in
+C and C++.
+
+Itanium ABI Zero-cost Exception Handling
+----------------------------------------
+
+Exception handling for most programming languages is designed to recover from
+conditions that rarely occur during general use of an application.  To that end,
+exception handling should not interfere with the main flow of an application's
+algorithm by performing checkpointing tasks, such as saving the current pc or
+register state.
+
+The Itanium ABI Exception Handling Specification defines a methodology for
+providing outlying data in the form of exception tables without inlining
+speculative exception handling code in the flow of an application's main
+algorithm.  Thus, the specification is said to add "zero-cost" to the normal
+execution of an application.
+
+A more complete description of the Itanium ABI exception handling runtime
+support of can be found at `Itanium C++ ABI: Exception Handling
+<http://www.codesourcery.com/cxx-abi/abi-eh.html>`_. A description of the
+exception frame format can be found at `Exception Frames
+<http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html>`_,
+with details of the DWARF 4 specification at `DWARF 4 Standard
+<http://dwarfstd.org/Dwarf4Std.php>`_.  A description for the C++ exception
+table formats can be found at `Exception Handling Tables
+<http://www.codesourcery.com/cxx-abi/exceptions.pdf>`_.
+
+Setjmp/Longjmp Exception Handling
+---------------------------------
+
+Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
+`llvm.eh.sjlj.setjmp`_ and `llvm.eh.sjlj.longjmp`_ to handle control flow for
+exception handling.
+
+For each function which does exception processing --- be it ``try``/``catch``
+blocks or cleanups --- that function registers itself on a global frame
+list. When exceptions are unwinding, the runtime uses this list to identify
+which functions need processing.
+
+Landing pad selection is encoded in the call site entry of the function
+context. The runtime returns to the function via `llvm.eh.sjlj.longjmp`_, where
+a switch table transfers control to the appropriate landing pad based on the
+index stored in the function context.
+
+In contrast to DWARF exception handling, which encodes exception regions and
+frame information in out-of-line tables, SJLJ exception handling builds and
+removes the unwind frame context at runtime. This results in faster exception
+handling at the expense of slower execution when no exceptions are thrown. As
+exceptions are, by their nature, intended for uncommon code paths, DWARF
+exception handling is generally preferred to SJLJ.
+
+Overview
+--------
+
+When an exception is thrown in LLVM code, the runtime does its best to find a
+handler suited to processing the circumstance.
+
+The runtime first attempts to find an *exception frame* corresponding to the
+function where the exception was thrown.  If the programming language supports
+exception handling (e.g. C++), the exception frame contains a reference to an
+exception table describing how to process the exception.  If the language does
+not support exception handling (e.g. C), or if the exception needs to be
+forwarded to a prior activation, the exception frame contains information about
+how to unwind the current activation and restore the state of the prior
+activation.  This process is repeated until the exception is handled. If the
+exception is not handled and no activations remain, then the application is
+terminated with an appropriate error message.
+
+Because different programming languages have different behaviors when handling
+exceptions, the exception handling ABI provides a mechanism for
+supplying *personalities*. An exception handling personality is defined by
+way of a *personality function* (e.g. ``__gxx_personality_v0`` in C++),
+which receives the context of the exception, an *exception structure*
+containing the exception object type and value, and a reference to the exception
+table for the current function.  The personality function for the current
+compile unit is specified in a *common exception frame*.
+
+The organization of an exception table is language dependent. For C++, an
+exception table is organized as a series of code ranges defining what to do if
+an exception occurs in that range. Typically, the information associated with a
+range defines which types of exception objects (using C++ *type info*) that are
+handled in that range, and an associated action that should take place. Actions
+typically pass control to a *landing pad*.
+
+A landing pad corresponds roughly to the code found in the ``catch`` portion of
+a ``try``/``catch`` sequence. When execution resumes at a landing pad, it
+receives an *exception structure* and a *selector value* corresponding to the
+*type* of exception thrown. The selector is then used to determine which *catch*
+should actually process the exception.
+
+LLVM Code Generation
+====================
+
+From a C++ developer's perspective, exceptions are defined in terms of the
+``throw`` and ``try``/``catch`` statements. In this section we will describe the
+implementation of LLVM exception handling in terms of C++ examples.
+
+Throw
+-----
+
+Languages that support exception handling typically provide a ``throw``
+operation to initiate the exception process. Internally, a ``throw`` operation
+breaks down into two steps.
+
+#. A request is made to allocate exception space for an exception structure.
+   This structure needs to survive beyond the current activation. This structure
+   will contain the type and value of the object being thrown.
+
+#. A call is made to the runtime to raise the exception, passing the exception
+   structure as an argument.
+
+In C++, the allocation of the exception structure is done by the
+``__cxa_allocate_exception`` runtime function. The exception raising is handled
+by ``__cxa_throw``. The type of the exception is represented using a C++ RTTI
+structure.
+
+Try/Catch
+---------
+
+A call within the scope of a *try* statement can potentially raise an
+exception. In those circumstances, the LLVM C++ front-end replaces the call with
+an ``invoke`` instruction. Unlike a call, the ``invoke`` has two potential
+continuation points:
+
+#. where to continue when the call succeeds as per normal, and
+
+#. where to continue if the call raises an exception, either by a throw or the
+   unwinding of a throw
+
+The term used to define a the place where an ``invoke`` continues after an
+exception is called a *landing pad*. LLVM landing pads are conceptually
+alternative function entry points where an exception structure reference and a
+type info index are passed in as arguments. The landing pad saves the exception
+structure reference and then proceeds to select the catch block that corresponds
+to the type info of the exception object.
+
+The LLVM `landingpad instruction <LangRef.html#i_landingpad>`_ is used to convey
+information about the landing pad to the back end. For C++, the ``landingpad``
+instruction returns a pointer and integer pair corresponding to the pointer to
+the *exception structure* and the *selector value* respectively.
+
+The ``landingpad`` instruction takes a reference to the personality function to
+be used for this ``try``/``catch`` sequence. The remainder of the instruction is
+a list of *cleanup*, *catch*, and *filter* clauses. The exception is tested
+against the clauses sequentially from first to last. The selector value is a
+positive number if the exception matched a type info, a negative number if it
+matched a filter, and zero if it matched a cleanup. If nothing is matched, the
+behavior of the program is `undefined`_. If a type info matched, then the
+selector value is the index of the type info in the exception table, which can
+be obtained using the `llvm.eh.typeid.for`_ intrinsic.
+
+Once the landing pad has the type info selector, the code branches to the code
+for the first catch. The catch then checks the value of the type info selector
+against the index of type info for that catch.  Since the type info index is not
+known until all the type infos have been gathered in the backend, the catch code
+must call the `llvm.eh.typeid.for`_ intrinsic to determine the index for a given
+type info. If the catch fails to match the selector then control is passed on to
+the next catch.
+
+Finally, the entry and exit of catch code is bracketed with calls to
+``__cxa_begin_catch`` and ``__cxa_end_catch``.
+
+* ``__cxa_begin_catch`` takes an exception structure reference as an argument
+  and returns the value of the exception object.
+
+* ``__cxa_end_catch`` takes no arguments. This function:
+
+  #. Locates the most recently caught exception and decrements its handler
+     count,
+
+  #. Removes the exception from the *caught* stack if the handler count goes to
+     zero, and
+
+  #. Destroys the exception if the handler count goes to zero and the exception
+     was not re-thrown by throw.
+
+  .. note::
+
+    a rethrow from within the catch may replace this call with a
+    ``__cxa_rethrow``.
+
+Cleanups
+--------
+
+A cleanup is extra code which needs to be run as part of unwinding a scope.  C++
+destructors are a typical example, but other languages and language extensions
+provide a variety of different kinds of cleanups. In general, a landing pad may
+need to run arbitrary amounts of cleanup code before actually entering a catch
+block. To indicate the presence of cleanups, a `landingpad
+instruction <LangRef.html#i_landingpad>`_ should have a *cleanup*
+clause. Otherwise, the unwinder will not stop at the landing pad if there are no
+catches or filters that require it to.
+
+.. note::
+
+  Do not allow a new exception to propagate out of the execution of a
+  cleanup. This can corrupt the internal state of the unwinder.  Different
+  languages describe different high-level semantics for these situations: for
+  example, C++ requires that the process be terminated, whereas Ada cancels both
+  exceptions and throws a third.
+
+When all cleanups are finished, if the exception is not handled by the current
+function, resume unwinding by calling the `resume
+instruction <LangRef.html#i_resume>`_, passing in the result of the
+``landingpad`` instruction for the original landing pad.
+
+Throw Filters
+-------------
+
+C++ allows the specification of which exception types may be thrown from a
+function. To represent this, a top level landing pad may exist to filter out
+invalid types. To express this in LLVM code the `landingpad
+instruction <LangRef.html#i_landingpad>`_ will have a filter clause. The clause
+consists of an array of type infos.  ``landingpad`` will return a negative value
+if the exception does not match any of the type infos. If no match is found then
+a call to ``__cxa_call_unexpected`` should be made, otherwise
+``_Unwind_Resume``.  Each of these functions requires a reference to the
+exception structure.  Note that the most general form of a ``landingpad``
+instruction can have any number of catch, cleanup, and filter clauses (though
+having more than one cleanup is pointless). The LLVM C++ front-end can generate
+such ``landingpad`` instructions due to inlining creating nested exception
+handling scopes.
+
+.. _undefined:
+
+Restrictions
+------------
+
+The unwinder delegates the decision of whether to stop in a call frame to that
+call frame's language-specific personality function. Not all unwinders guarantee
+that they will stop to perform cleanups. For example, the GNU C++ unwinder
+doesn't do so unless the exception is actually caught somewhere further up the
+stack.
+
+In order for inlining to behave correctly, landing pads must be prepared to
+handle selector results that they did not originally advertise. Suppose that a
+function catches exceptions of type ``A``, and it's inlined into a function that
+catches exceptions of type ``B``. The inliner will update the ``landingpad``
+instruction for the inlined landing pad to include the fact that ``B`` is also
+caught. If that landing pad assumes that it will only be entered to catch an
+``A``, it's in for a rude awakening.  Consequently, landing pads must test for
+the selector results they understand and then resume exception propagation with
+the `resume instruction <LangRef.html#i_resume>`_ if none of the conditions
+match.
+
+Exception Handling Intrinsics
+=============================
+
+In addition to the ``landingpad`` and ``resume`` instructions, LLVM uses several
+intrinsic functions (name prefixed with ``llvm.eh``) to provide exception
+handling information at various points in generated code.
+
+.. _llvm.eh.typeid.for:
+
+llvm.eh.typeid.for
+------------------
+
+.. code-block:: llvm
+
+  i32 @llvm.eh.typeid.for(i8* %type_info)
+
+
+This intrinsic returns the type info index in the exception table of the current
+function.  This value can be used to compare against the result of
+``landingpad`` instruction.  The single argument is a reference to a type info.
+
+.. _llvm.eh.sjlj.setjmp:
+
+llvm.eh.sjlj.setjmp
+-------------------
+
+.. code-block:: llvm
+
+  i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
+
+For SJLJ based exception handling, this intrinsic forces register saving for the
+current function and stores the address of the following instruction for use as
+a destination address by `llvm.eh.sjlj.longjmp`_. The buffer format and the
+overall functioning of this intrinsic is compatible with the GCC
+``__builtin_setjmp`` implementation allowing code built with the clang and GCC
+to interoperate.
+
+The single parameter is a pointer to a five word buffer in which the calling
+context is saved. The front end places the frame pointer in the first word, and
+the target implementation of this intrinsic should place the destination address
+for a `llvm.eh.sjlj.longjmp`_ in the second word. The following three words are
+available for use in a target-specific manner.
+
+.. _llvm.eh.sjlj.longjmp:
+
+llvm.eh.sjlj.longjmp
+--------------------
+
+.. code-block:: llvm
+
+  void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
+
+For SJLJ based exception handling, the ``llvm.eh.sjlj.longjmp`` intrinsic is
+used to implement ``__builtin_longjmp()``. The single parameter is a pointer to
+a buffer populated by `llvm.eh.sjlj.setjmp`_. The frame pointer and stack
+pointer are restored from the buffer, then control is transferred to the
+destination address.
+
+llvm.eh.sjlj.lsda
+-----------------
+
+.. code-block:: llvm
+
+  i8* @llvm.eh.sjlj.lsda()
+
+For SJLJ based exception handling, the ``llvm.eh.sjlj.lsda`` intrinsic returns
+the address of the Language Specific Data Area (LSDA) for the current
+function. The SJLJ front-end code stores this address in the exception handling
+function context for use by the runtime.
+
+llvm.eh.sjlj.callsite
+---------------------
+
+.. code-block:: llvm
+
+  void @llvm.eh.sjlj.callsite(i32 %call_site_num)
+
+For SJLJ based exception handling, the ``llvm.eh.sjlj.callsite`` intrinsic
+identifies the callsite value associated with the following ``invoke``
+instruction. This is used to ensure that landing pad entries in the LSDA are
+generated in matching order.
+
+Asm Table Formats
+=================
+
+There are two tables that are used by the exception handling runtime to
+determine which actions should be taken when an exception is thrown.
+
+Exception Handling Frame
+------------------------
+
+An exception handling frame ``eh_frame`` is very similar to the unwind frame
+used by DWARF debug info. The frame contains all the information necessary to
+tear down the current frame and restore the state of the prior frame. There is
+an exception handling frame for each function in a compile unit, plus a common
+exception handling frame that defines information common to all functions in the
+unit.
+
+Exception Tables
+----------------
+
+An exception table contains information about what actions to take when an
+exception is thrown in a particular part of a function's code. There is one
+exception table per function, except leaf functions and functions that have
+calls only to non-throwing functions. They do not need an exception table.
diff --git a/docs/subsystems.rst b/docs/subsystems.rst
index 28ad020..27dff6b 100644
--- a/docs/subsystems.rst
+++ b/docs/subsystems.rst
@@ -9,6 +9,7 @@ Subsystem Documentation
    AliasAnalysis
    BranchWeightMetadata
    Bugpoint
+   ExceptionHandling
    LinkTimeOptimization
    SegmentedStacks
    TableGenFundamentals
@@ -47,7 +48,7 @@ Subsystem Documentation
    This document describes the design and philosophy behind the LLVM
    source-level debugger.
     
-* `Zero Cost Exception handling in LLVM <ExceptionHandling.html>`_
+* :ref:`exception_handling`
     
    This document describes the design and implementation of exception handling
    in LLVM.
author	Bill Wendling <isanbard@gmail.com>	2012-06-27 07:20:57 +0000
committer	Bill Wendling <isanbard@gmail.com>	2012-06-27 07:20:57 +0000
commit	7d85f87acb4d46cfd315a08f6f64b23818eb47e4 (patch)
tree	fb88c07cd4a4adc6c3009dc7213042e9eca95318 /docs
parent	e246b52d2b02753a0064fb7e984148fff55d2872 (diff)
download	external_llvm-7d85f87acb4d46cfd315a08f6f64b23818eb47e4.zip external_llvm-7d85f87acb4d46cfd315a08f6f64b23818eb47e4.tar.gz external_llvm-7d85f87acb4d46cfd315a08f6f64b23818eb47e4.tar.bz2