| <!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="#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_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'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 | |
| 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 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 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 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 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 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>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. 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 | |
| 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>__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="cleanups">Cleanups</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. 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> | |
| <!-- ======================================================================= --> | |
| <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_selector"><tt>llvm.eh.selector</tt></a>. The arguments are the | |
| 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> | |
| <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.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 | |
| 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. 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_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.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 | |
| 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'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>Testing/Testing/Testing.</p></li> | |
| </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> |