First draft of exception handling doc.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@35100 91177308-0d34-0410-b5e6-96231b3b80d8
author: Jim Laskey <jlaskey@mac.com> 2007-03-14 19:29:42 +0000
committer: Jim Laskey <jlaskey@mac.com> 2007-03-14 19:29:42 +0000
commit: d0d39b685b9a13022896fcc273b29e135b16199b (patch)
tree: 70e3aa52116f1ac41723e0df5655a160384a50f2 /docs
parent: 91f76be8ac4eff2d4b9606e37212ccb6a586fb69 (diff)
download: llvm-d0d39b685b9a13022896fcc273b29e135b16199b.tar.gz
llvm-d0d39b685b9a13022896fcc273b29e135b16199b.tar.bz2
llvm-d0d39b685b9a13022896fcc273b29e135b16199b.tar.xz
1 files changed, 460 insertions, 0 deletions
diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html
new file mode 100644
index 0000000000..d515b4cd0e
--- /dev/null
+++ b/docs/ExceptionHandling.html
@@ -0,0 +1,460 @@
+<!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>
+  <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<div class="doc_title">Exception Handling in LLVM</div>
+
+<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="#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="#finally">Finallys</a></li>
+    <li><a href="#throw_filters">Throw Filters</a></li>
+  </ol></li>
+  <li><a href="#intrinsics">Exception Handling Intrinsics</a>
+  <ol>
+  	<li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a></li>
+  	<li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a></li>
+  	<li><a href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a></li>
+  	<li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</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>
+  <li><a href="#todo">ToDo</a></li>
+</ul>
+</td>
+</tr></table>
+
+<div class="doc_author">
+  <p>Written by <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
+</div>
+
+
+<!-- *********************************************************************** -->
+<div class="doc_section"><a name="introduction">Introduction</a></div> 
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<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
+C/C++.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="itanium">Itanium ABI Zero-cost Exception Handling</a>
+</div>
+
+<div class="doc_text">
+
+<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&apos;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&apos;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
+specification at <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3
+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>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="overview">Overview</a>
+</div>
+
+<div class="doc_text">
+
+<p>When an exception is thrown in llvm code, the runtime does a best effort to
+find a handler suited to process 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 (ex.
+C++) supports exception handling, the exception frame contains a reference to an
+exception table describing how to process the exception.  If the language (ex.
+C) does not support exception handling 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>Since 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> (ex. for C++ <tt>__gxx_personality_v0</tt>) which
+receives the context of the exception, an <i>exception structure</i> containing
+the exception object type and value, and a reference 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 to the code found in the catch portion of a
+try/catch sequence.  When execution resumes at a landing pad, it receives the
+exception structure and a selector corresponding to the <i>type</i> of exception
+thrown.  The selector is then used to determine which catch should actually
+process the exception.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_section">
+  <a name="codegen">LLVM Code Generation</a>
+</div>
+
+<div class="doc_text">
+
+<p>At the time of this writing, only C++ exception handling support is available
+in LLVM.  So the remainder of this document will be somewhat C++-centric.</p>
+
+<p>From the C++ developers perspective, exceptions are defined in terms of the
+<tt>throw</tt> and <tt>try/catch</tt> statements.  In this section we will
+describe the implementation of llvm exception handling in terms of C++
+examples.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="throw">Throw</a>
+</div>
+
+<div class="doc_text">
+
+<p>Languages that support exception handling typically provide a <tt>throw</tt>
+operation to initiate the exception process.  Internally, a throw operation
+breaks down into two steps.  First, 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.  Second, a call is made to the runtime to raise the
+exception, passing the exception structure as an argument.</p>
+
+<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 type info structure.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="try_catch">Try/Catch</a>
+</div>
+
+<div class="doc_text">
+
+<p>A call within the scope of a try statement can potential raise an exception.
+In those circumstances, the LLVM C++ front-end replaces the call with an
+<tt>invoke</tt> 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.</p>
+
+<p>The term used to define a the place where an invoke continues after an
+exception is called a <i>landing pad</i>.  LLVM landing pads are conceptually
+alternative entry points into where a 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>Two llvm intrinsic functions are used convey information about the landing
+pad to the back end.</p>
+
+<p><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a> takes no
+arguments and returns the exception structure reference.  The backend replaces
+this intrinsic with the code that accesses the first argument of a call.  The
+LLVM C++ front end generates code to save this value in an alloca location for
+further use in the landing pad and catch code.</p>
+
+<p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of
+three arguments.  The first argument is the reference to the exception
+structure. The second argument is a reference to the personality function to be
+used for this try catch sequence. The remaining arguments are references to the
+type infos for each of the catch statements in the order they should be tested.
+The <i>catch all</i> (...) is represented with a <tt>null i8*</tt>.  The result
+of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is the index of
+the type info in the corresponding exception table. The LLVM C++ front end
+generates code to save this value in an alloca location for further use in the
+landing pad and catch code.</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 info have been gathered in the backend,
+the catch code will 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. Note: Since the landing
+pad will not be used if there is no match in the list of type info on the call
+to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>, then neither the
+last catch nor <i>catch all</i> need to perform the the check against the
+selector.</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>.
+<tt>__cxa_begin_catch</tt> takes a exception structure reference as an argument
+and returns the value of the exception object.</tt>  <tt>__cxa_end_catch</tt>
+takes a exception structure reference as an argument. This function clears the
+exception from the exception space.  Note: a rethrow from within the catch may
+replace this call with a <tt>__cxa_rethrow</tt>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="finallys">Finallys</a>
+</div>
+
+<div class="doc_text">
+
+<p>To handle destructors and cleanups in try code, control may not run directly
+from a landing pad to the first catch.  Control may actually flow from the
+landing pad to clean up code and then to the first catch.  Since the required
+clean up for each invoke in a try may be different (ex., intervening
+constructor), there may be several landing pads for a given try.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="throw_filters">Throw Filters</a>
+</div>
+
+<div class="doc_text">
+
+<p>C++ allows the specification of which exception types that can 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 landing pad will call <a
+href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a> instead of <a
+href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>.  The arguments are the
+same, but what gets created in the exception table is different. <a
+href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a>  will return a negative value
+if it doesn't find a match. 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 require a reference to the
+exception structure.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_section">
+  <a name="intrinsics">Exception Handling Intrinsics</a>
+</div>
+
+<div class="doc_text">
+
+<p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to
+provide exception handling information at various points in generated code.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+  <a name="llvm_eh_exception">llvm.eh.exception</a>
+</div>
+
+<div class="doc_text">
+<pre>
+  i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>( )
+</pre>
+
+<p>This intrinsic indicates that the exception structure is available at this
+point in the code.  The backend will replace this intrinsic with code to fetch
+the first argument of a call.  The effect is that the intrinsic result is the
+exception structure reference.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+  <a name="llvm_eh_selector">llvm.eh.selector</a>
+</div>
+
+<div class="doc_text">
+<pre>
+  i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, i8*, ...)
+</pre>
+
+<p>This intrinsic indicates that the exception selector is available at this
+point in the code.  The backend will replace this intrinsic with code to fetch
+the second argument of a call.  The effect is that the intrinsic result is the
+exception selector.</p>
+
+<p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of
+three arguments.  The first argument is the reference to the exception
+structure. The second argument is a reference to the personality function to be
+used for this try catch sequence. The remaining arguments are references to the
+type infos for each of the catch statements in the order they should be tested.
+The <i>catch all</i> (...) is represented with a <tt>null i8*</tt>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+  <a name="llvm_eh_filter">llvm.eh.filter</a>
+</div>
+
+<div class="doc_text">
+<pre>
+  i32 %<a href="#llvm_eh_filter">llvm.eh.filter</a>(i8*, i8*, i8*, ...)
+</pre>
+
+<p>This intrinsic indicates that the exception selector is available at this
+point in the code.  The backend will replace this intrinsic with code to fetch
+the second argument of a call.  The effect is that the intrinsic result is the
+exception selector.</p>
+
+<p><a href="#llvm_eh_filter"><tt>llvm.eh.filter</tt></a> takes a minimum of
+three arguments.  The first argument is the reference to the exception
+structure. The second argument is a reference to the personality function to be
+used for this function. The remaining arguments are references to the type infos
+for each type that can be thrown by the current function.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+  <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a>
+</div>
+
+<div class="doc_text">
+<pre>
+  i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*)
+</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="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>.  The single argument is
+a reference to a type info.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_section">
+  <a name="asm">Asm Table Formats</a>
+</div>
+
+<div class="doc_text">
+
+<p>There are two tables that are used by the exception handling runtime to
+determine which actions should take place when an exception is thrown.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="unwind_tables">Exception Handling Frame</a>
+</div>
+
+<div class="doc_text">
+
+<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>
+
+<p>Todo - Table details here.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="exception_tables">Exception Tables</a>
+</div>
+
+<div class="doc_text">
+
+<p>An exception table contains information about what actions to take when an
+exception is thrown in a particular part of a function&apos;s code.  There is
+one exception table per function except leaf routines and functions that have
+only calls to non-throwing functions will not need an exception table.</p>
+
+<p>Todo - Table details here.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_section">
+  <a name="todo">ToDo</a>
+</div>
+
+<div class="doc_text">
+
+<ol>
+
+<li><p>Need to create landing pads for code in between explicit landing pads. 
+The landing pads will have a zero action and a NULL landing pad address and are
+used to inform the runtime that the exception should be rethrown.</li></p>
+
+<li><p>Actions for a given function should be folded to save space.</p></li>
+
+<li><p>Filters for inlined functions need to be handled more extensively.
+Currently it&apos;s hardwired for one filter per function.</li></p>
+
+<li><p>Testing/Testing/Testing.</li></p>
+
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+  src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+  <a href="http://validator.w3.org/check/referer"><img
+  src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+  <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
+  <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+  Last modified: $Date$
+</address>
+
+</body>
+</html>
author	Jim Laskey <jlaskey@mac.com>	2007-03-14 19:29:42 +0000
committer	Jim Laskey <jlaskey@mac.com>	2007-03-14 19:29:42 +0000
commit	d0d39b685b9a13022896fcc273b29e135b16199b (patch)
tree	70e3aa52116f1ac41723e0df5655a160384a50f2 /docs
parent	91f76be8ac4eff2d4b9606e37212ccb6a586fb69 (diff)
download	llvm-d0d39b685b9a13022896fcc273b29e135b16199b.tar.gz llvm-d0d39b685b9a13022896fcc273b29e135b16199b.tar.bz2 llvm-d0d39b685b9a13022896fcc273b29e135b16199b.tar.xz