Changes in directory llvm/docs:
ExceptionHandling.html added (r1.1) --- Log message: First draft of exception handling doc. --- Diffs of the changes: (+460 -0) ExceptionHandling.html | 460 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 460 insertions(+) Index: llvm/docs/ExceptionHandling.html diff -c /dev/null llvm/docs/ExceptionHandling.html:1.1 *** /dev/null Wed Mar 14 14:29:52 2007 --- llvm/docs/ExceptionHandling.html Wed Mar 14 14:29:42 2007 *************** *** 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:[EMAIL PROTECTED]">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 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'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'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:[EMAIL PROTECTED]">Chris Lattner</a><br> + <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> + Last modified: $Date: 2007/03/14 19:29:42 $ + </address> + + </body> + </html> _______________________________________________ llvm-commits mailing list llvm-commits@cs.uiuc.edu http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits