<ol>
<li><a href="#throw">Throw</a></li>
<li><a href="#try_catch">Try/Catch</a></li>
- <li><a href="#finallys">Finallys</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_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>
<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
+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
+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-
+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
<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
+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
<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
+alternative function entry points 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><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>
+used for this try catch sequence. Each of the remaining arguments is either a
+reference to the type info for a catch statement,
+a <a href="#throw_filters">filter</a> expression,
+or the number zero representing a <a href="#cleanups">cleanup</a>.
+The exception is tested against the arguments sequentially from first to last.
+The result of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> 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 behaviour of
+the program is <a href="#restrictions">undefined</a>.
+The LLVM C++ front end generates code to save the selector value in an alloca
+location for further use in the landing pad and catch code.
+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
<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>
+and returns the value of the exception object. <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 class="doc_subsection">
- <a name="finallys">Finallys</a>
+ <a name="cleanups">Cleanups</a>
</div>
<div class="doc_text">
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>
+constructor), there may be several landing pads for a given try. If cleanups
+need to be run, the number zero should be passed as the last
+<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument.
+However for C++ a <tt>null i8*</tt> <a href="#restrictions">must</a> be passed
+instead.
+</p>
</div>
<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
+length of the filter expression (the number of type infos plus one), followed by
+the type infos themselves.
+<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> 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 require a reference to the
exception structure.</p>
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="restrictions">Restrictions</a>
+</div>
+
+<div class="doc_text">
+
+<p>The semantics of the invoke instruction require that any exception that
+unwinds through an invoke call should result in a branch to the invoke's unwind
+label. However such a branch will only happen if the
+<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> matches.
+Thus in order to ensure correct operation, the front-end must only generate
+<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls that are
+guaranteed to always match whatever exception unwinds through the invoke.
+For most languages it is enough to pass zero, indicating the presence of
+a <a href="#cleanups">cleanup</a>, as the last
+<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument.
+However for C++ this is not sufficient, because the C++ personality function
+will terminate the program if it detects that unwinding the exception only
+results in matches with cleanups. For C++ a <tt>null i8*</tt> should
+be passed as the last
+<a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument instead.
+This is interpreted as a catch-all by the C++ personality function, and will
+always match.
+</p>
+
+</div>
+
<!-- ======================================================================= -->
<div class="doc_section">
<a name="format_common_intrinsics">Exception Handling Intrinsics</a>
<div class="doc_text">
<pre>
- i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, i8*, ...)
+ i32 %<a href="#llvm_eh_selector">llvm.eh.selector.i32</a>(i8*, i8*, i8*, ...)
+ i64 %<a href="#llvm_eh_selector">llvm.eh.selector.i64</a>(i8*, i8*, i8*, ...)
</pre>
<p>This intrinsic indicates that the exception selector is available at this
<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>
+used for this try catch sequence. Each of the remaining arguments is either a
+reference to the type info for a catch statement,
+a <a href="#throw_filters">filter</a> expression,
+or the number zero representing a <a href="#cleanups">cleanup</a>.
+The exception is tested against the arguments sequentially from first to last.
+The result of the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> 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 behaviour 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>
</div>
<div class="doc_text">
<pre>
- i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*)
+ i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i32</a>(i8*)
+ i64 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for.i64</a>(i8*)
</pre>
<p>This intrinsic returns the type info index in the exception table of the
<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's code. There is
+exception is thrown in a particular part of a function'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>
<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's hardwired for one filter per function.</li></p>
-
-<li><p>Testing/Testing/Testing.</li></p>
+<li><p>Testing/Testing/Testing.</p></li>
</ol>
projects / oota-llvm.git / blobdiff