Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <title>Exception Handling in LLVM</title> |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 6 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
Eric Christopher | 61f6978 | 2009-09-09 01:44:53 +0000 | [diff] [blame] | 7 | <meta name="description" |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 8 | content="Exception Handling in LLVM."> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 9 | <link rel="stylesheet" href="llvm.css" type="text/css"> |
| 10 | </head> |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 11 | |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 12 | <body> |
| 13 | |
| 14 | <div class="doc_title">Exception Handling in LLVM</div> |
| 15 | |
| 16 | <table class="layout" style="width:100%"> |
| 17 | <tr class="layout"> |
| 18 | <td class="left"> |
| 19 | <ul> |
| 20 | <li><a href="#introduction">Introduction</a> |
| 21 | <ol> |
| 22 | <li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li> |
Jim Grosbach | 00484d1 | 2009-08-22 01:42:39 +0000 | [diff] [blame] | 23 | <li><a href="#sjlj">Setjmp/Longjmp Exception Handling</a></li> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 24 | <li><a href="#overview">Overview</a></li> |
| 25 | </ol></li> |
| 26 | <li><a href="#codegen">LLVM Code Generation</a> |
| 27 | <ol> |
| 28 | <li><a href="#throw">Throw</a></li> |
| 29 | <li><a href="#try_catch">Try/Catch</a></li> |
Duncan Sands | 6590b04 | 2007-08-27 15:47:50 +0000 | [diff] [blame] | 30 | <li><a href="#cleanups">Cleanups</a></li> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 31 | <li><a href="#throw_filters">Throw Filters</a></li> |
Duncan Sands | 6590b04 | 2007-08-27 15:47:50 +0000 | [diff] [blame] | 32 | <li><a href="#restrictions">Restrictions</a></li> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 33 | </ol></li> |
Duncan Sands | 8036ca4 | 2007-03-30 12:22:09 +0000 | [diff] [blame] | 34 | <li><a href="#format_common_intrinsics">Exception Handling Intrinsics</a> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 35 | <ol> |
| 36 | <li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a></li> |
| 37 | <li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a></li> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 38 | <li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li> |
Jim Grosbach | f957012 | 2009-05-14 00:46:35 +0000 | [diff] [blame] | 39 | <li><a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a></li> |
| 40 | <li><a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a></li> |
Jim Grosbach | 1b747ad | 2009-08-11 00:09:57 +0000 | [diff] [blame] | 41 | <li><a href="#llvm_eh_sjlj_lsda"><tt>llvm.eh.sjlj.lsda</tt></a></li> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 42 | </ol></li> |
| 43 | <li><a href="#asm">Asm Table Formats</a> |
| 44 | <ol> |
| 45 | <li><a href="#unwind_tables">Exception Handling Frame</a></li> |
| 46 | <li><a href="#exception_tables">Exception Tables</a></li> |
| 47 | </ol></li> |
| 48 | <li><a href="#todo">ToDo</a></li> |
| 49 | </ul> |
| 50 | </td> |
| 51 | </tr></table> |
| 52 | |
| 53 | <div class="doc_author"> |
| 54 | <p>Written by <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p> |
| 55 | </div> |
| 56 | |
| 57 | |
| 58 | <!-- *********************************************************************** --> |
Eric Christopher | 61f6978 | 2009-09-09 01:44:53 +0000 | [diff] [blame] | 59 | <div class="doc_section"><a name="introduction">Introduction</a></div> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 60 | <!-- *********************************************************************** --> |
| 61 | |
| 62 | <div class="doc_text"> |
| 63 | |
| 64 | <p>This document is the central repository for all information pertaining to |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 65 | exception handling in LLVM. It describes the format that LLVM exception |
| 66 | handling information takes, which is useful for those interested in creating |
| 67 | front-ends or dealing directly with the information. Further, this document |
| 68 | provides specific examples of what exception handling information is used for |
| 69 | in C/C++.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 70 | |
| 71 | </div> |
| 72 | |
| 73 | <!-- ======================================================================= --> |
| 74 | <div class="doc_subsection"> |
| 75 | <a name="itanium">Itanium ABI Zero-cost Exception Handling</a> |
| 76 | </div> |
| 77 | |
| 78 | <div class="doc_text"> |
| 79 | |
| 80 | <p>Exception handling for most programming languages is designed to recover from |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 81 | conditions that rarely occur during general use of an application. To that |
| 82 | end, exception handling should not interfere with the main flow of an |
| 83 | application's algorithm by performing checkpointing tasks, such as saving the |
| 84 | current pc or register state.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 85 | |
| 86 | <p>The Itanium ABI Exception Handling Specification defines a methodology for |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 87 | providing outlying data in the form of exception tables without inlining |
| 88 | speculative exception handling code in the flow of an application's main |
| 89 | algorithm. Thus, the specification is said to add "zero-cost" to the normal |
| 90 | execution of an application.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 91 | |
| 92 | <p>A more complete description of the Itanium ABI exception handling runtime |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 93 | support of can be found at |
| 94 | <a href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI: |
| 95 | Exception Handling</a>. A description of the exception frame format can be |
| 96 | found at |
| 97 | <a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception |
| 98 | Frames</a>, with details of the DWARF 3 specification at |
| 99 | <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3 Standard</a>. |
| 100 | A description for the C++ exception table formats can be found at |
| 101 | <a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling |
| 102 | Tables</a>.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 103 | |
| 104 | </div> |
| 105 | |
| 106 | <!-- ======================================================================= --> |
| 107 | <div class="doc_subsection"> |
Jim Grosbach | 00484d1 | 2009-08-22 01:42:39 +0000 | [diff] [blame] | 108 | <a name="sjlj">Setjmp/Longjmp Exception Handling</a> |
| 109 | </div> |
| 110 | |
| 111 | <div class="doc_text"> |
| 112 | |
| 113 | <p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics |
| 114 | <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and |
| 115 | <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> to |
| 116 | handle control flow for exception handling.</p> |
| 117 | |
| 118 | <p>For each function which does exception processing, be it try/catch blocks |
| 119 | or cleanups, that function registers itself on a global frame list. When |
| 120 | exceptions are being unwound, the runtime uses this list to identify which |
| 121 | functions need processing.<p> |
| 122 | |
| 123 | <p>Landing pad selection is encoded in the call site entry of the function |
| 124 | context. The runtime returns to the function via |
| 125 | <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>, where |
| 126 | a switch table transfers control to the appropriate landing pad based on |
| 127 | the index stored in the function context.</p> |
| 128 | |
| 129 | <p>In contrast to DWARF exception handling, which encodes exception regions |
| 130 | and frame information in out-of-line tables, SJLJ exception handling |
| 131 | builds and removes the unwind frame context at runtime. This results in |
| 132 | faster exception handling at the expense of slower execution when no |
| 133 | exceptions are thrown. As exceptions are, by their nature, intended for |
| 134 | uncommon code paths, DWARF exception handling is generally preferred to |
| 135 | SJLJ.</p> |
| 136 | </div> |
| 137 | |
| 138 | <!-- ======================================================================= --> |
| 139 | <div class="doc_subsection"> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 140 | <a name="overview">Overview</a> |
| 141 | </div> |
| 142 | |
| 143 | <div class="doc_text"> |
| 144 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 145 | <p>When an exception is thrown in LLVM code, the runtime does its best to find a |
| 146 | handler suited to processing the circumstance.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 147 | |
| 148 | <p>The runtime first attempts to find an <i>exception frame</i> corresponding to |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 149 | the function where the exception was thrown. If the programming language |
| 150 | (e.g. C++) supports exception handling, the exception frame contains a |
| 151 | reference to an exception table describing how to process the exception. If |
| 152 | the language (e.g. C) does not support exception handling, or if the |
| 153 | exception needs to be forwarded to a prior activation, the exception frame |
| 154 | contains information about how to unwind the current activation and restore |
| 155 | the state of the prior activation. This process is repeated until the |
| 156 | exception is handled. If the exception is not handled and no activations |
| 157 | remain, then the application is terminated with an appropriate error |
| 158 | message.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 159 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 160 | <p>Because different programming languages have different behaviors when |
| 161 | handling exceptions, the exception handling ABI provides a mechanism for |
| 162 | supplying <i>personalities.</i> An exception handling personality is defined |
| 163 | by way of a <i>personality function</i> (e.g. <tt>__gxx_personality_v0</tt> |
| 164 | in C++), which receives the context of the exception, an <i>exception |
| 165 | structure</i> containing the exception object type and value, and a reference |
| 166 | to the exception table for the current function. The personality function |
| 167 | for the current compile unit is specified in a <i>common exception |
| 168 | frame</i>.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 169 | |
| 170 | <p>The organization of an exception table is language dependent. For C++, an |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 171 | exception table is organized as a series of code ranges defining what to do |
| 172 | if an exception occurs in that range. Typically, the information associated |
| 173 | with a range defines which types of exception objects (using C++ <i>type |
| 174 | info</i>) that are handled in that range, and an associated action that |
| 175 | should take place. Actions typically pass control to a <i>landing |
| 176 | pad</i>.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 177 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 178 | <p>A landing pad corresponds to the code found in the <i>catch</i> portion of |
| 179 | a <i>try</i>/<i>catch</i> sequence. When execution resumes at a landing |
| 180 | pad, it receives the exception structure and a selector corresponding to |
| 181 | the <i>type</i> of exception thrown. The selector is then used to determine |
| 182 | which <i>catch</i> should actually process the exception.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 183 | |
| 184 | </div> |
| 185 | |
| 186 | <!-- ======================================================================= --> |
| 187 | <div class="doc_section"> |
| 188 | <a name="codegen">LLVM Code Generation</a> |
| 189 | </div> |
| 190 | |
| 191 | <div class="doc_text"> |
| 192 | |
| 193 | <p>At the time of this writing, only C++ exception handling support is available |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 194 | in LLVM. So the remainder of this document will be somewhat C++-centric.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 195 | |
| 196 | <p>From the C++ developers perspective, exceptions are defined in terms of the |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 197 | <tt>throw</tt> and <tt>try</tt>/<tt>catch</tt> statements. In this section |
| 198 | we will describe the implementation of LLVM exception handling in terms of |
| 199 | C++ examples.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 200 | |
| 201 | </div> |
| 202 | |
| 203 | <!-- ======================================================================= --> |
| 204 | <div class="doc_subsection"> |
| 205 | <a name="throw">Throw</a> |
| 206 | </div> |
| 207 | |
| 208 | <div class="doc_text"> |
| 209 | |
| 210 | <p>Languages that support exception handling typically provide a <tt>throw</tt> |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 211 | operation to initiate the exception process. Internally, a throw operation |
| 212 | breaks down into two steps. First, a request is made to allocate exception |
| 213 | space for an exception structure. This structure needs to survive beyond the |
| 214 | current activation. This structure will contain the type and value of the |
| 215 | object being thrown. Second, a call is made to the runtime to raise the |
| 216 | exception, passing the exception structure as an argument.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 217 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 218 | <p>In C++, the allocation of the exception structure is done by |
| 219 | the <tt>__cxa_allocate_exception</tt> runtime function. The exception |
| 220 | raising is handled by <tt>__cxa_throw</tt>. The type of the exception is |
| 221 | represented using a C++ RTTI structure.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 222 | |
| 223 | </div> |
| 224 | |
| 225 | <!-- ======================================================================= --> |
| 226 | <div class="doc_subsection"> |
| 227 | <a name="try_catch">Try/Catch</a> |
| 228 | </div> |
| 229 | |
| 230 | <div class="doc_text"> |
| 231 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 232 | <p>A call within the scope of a <i>try</i> statement can potentially raise an |
| 233 | exception. In those circumstances, the LLVM C++ front-end replaces the call |
| 234 | with an <tt>invoke</tt> instruction. Unlike a call, the <tt>invoke</tt> has |
| 235 | two potential continuation points: where to continue when the call succeeds |
| 236 | as per normal; and where to continue if the call raises an exception, either |
| 237 | by a throw or the unwinding of a throw.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 238 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 239 | <p>The term used to define a the place where an <tt>invoke</tt> continues after |
| 240 | an exception is called a <i>landing pad</i>. LLVM landing pads are |
| 241 | conceptually alternative function entry points where an exception structure |
| 242 | reference and a type info index are passed in as arguments. The landing pad |
| 243 | saves the exception structure reference and then proceeds to select the catch |
| 244 | block that corresponds to the type info of the exception object.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 245 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 246 | <p>Two LLVM intrinsic functions are used to convey information about the landing |
| 247 | pad to the back end.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 248 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 249 | <ol> |
| 250 | <li><a href="#llvm_eh_exception"><tt>llvm.eh.exception</tt></a> takes no |
| 251 | arguments and returns a pointer to the exception structure. This only |
| 252 | returns a sensible value if called after an <tt>invoke</tt> has branched |
| 253 | to a landing pad. Due to code generation limitations, it must currently |
| 254 | be called in the landing pad itself.</li> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 255 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 256 | <li><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum |
| 257 | of three arguments. The first argument is the reference to the exception |
| 258 | structure. The second argument is a reference to the personality function |
| 259 | to be used for this <tt>try</tt>/<tt>catch</tt> sequence. Each of the |
| 260 | remaining arguments is either a reference to the type info for |
| 261 | a <tt>catch</tt> statement, a <a href="#throw_filters">filter</a> |
| 262 | expression, or the number zero (<tt>0</tt>) representing |
| 263 | a <a href="#cleanups">cleanup</a>. The exception is tested against the |
| 264 | arguments sequentially from first to last. The result of |
| 265 | the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a |
| 266 | positive number if the exception matched a type info, a negative number if |
| 267 | it matched a filter, and zero if it matched a cleanup. If nothing is |
| 268 | matched, the behaviour of the program |
| 269 | is <a href="#restrictions">undefined</a>. This only returns a sensible |
| 270 | value if called after an <tt>invoke</tt> has branched to a landing pad. |
| 271 | Due to codegen limitations, it must currently be called in the landing pad |
| 272 | itself. If a type info matched, then the selector value is the index of |
| 273 | the type info in the exception table, which can be obtained using the |
| 274 | <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> |
| 275 | intrinsic.</li> |
| 276 | </ol> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 277 | |
| 278 | <p>Once the landing pad has the type info selector, the code branches to the |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 279 | code for the first catch. The catch then checks the value of the type info |
| 280 | selector against the index of type info for that catch. Since the type info |
| 281 | index is not known until all the type info have been gathered in the backend, |
| 282 | the catch code will call the |
| 283 | <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic |
| 284 | to determine the index for a given type info. If the catch fails to match |
| 285 | the selector then control is passed on to the next catch. Note: Since the |
| 286 | landing pad will not be used if there is no match in the list of type info on |
| 287 | the call to <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>, then |
| 288 | neither the last catch nor <i>catch all</i> need to perform the check |
| 289 | against the selector.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 290 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 291 | <p>Finally, the entry and exit of catch code is bracketed with calls |
| 292 | to <tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.</p> |
| 293 | |
| 294 | <ul> |
| 295 | <li><tt>__cxa_begin_catch</tt> takes a exception structure reference as an |
| 296 | argument and returns the value of the exception object.</li> |
| 297 | |
Bill Wendling | 169e1b0 | 2009-09-10 22:14:16 +0000 | [diff] [blame] | 298 | <li><tt>__cxa_end_catch</tt> takes no arguments. This function:<br><br> |
| 299 | <ol> |
Bill Wendling | 808b9ce | 2009-09-10 22:12:50 +0000 | [diff] [blame] | 300 | <li>Locates the most recently caught exception and decrements its handler |
| 301 | count,</li> |
| 302 | <li>Removes the exception from the "caught" stack if the handler count |
| 303 | goes to zero, and</li> |
| 304 | <li>Destroys the exception if the handler count goes to zero, and the |
| 305 | exception was not re-thrown by throw.</li> |
Bill Wendling | 169e1b0 | 2009-09-10 22:14:16 +0000 | [diff] [blame] | 306 | </ol> |
Bill Wendling | 808b9ce | 2009-09-10 22:12:50 +0000 | [diff] [blame] | 307 | <p>Note: a rethrow from within the catch may replace this call with |
| 308 | a <tt>__cxa_rethrow</tt>.</p></li> |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 309 | </ul> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 310 | |
| 311 | </div> |
| 312 | |
| 313 | <!-- ======================================================================= --> |
| 314 | <div class="doc_subsection"> |
Duncan Sands | 6590b04 | 2007-08-27 15:47:50 +0000 | [diff] [blame] | 315 | <a name="cleanups">Cleanups</a> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 316 | </div> |
| 317 | |
| 318 | <div class="doc_text"> |
| 319 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 320 | <p>To handle destructors and cleanups in <tt>try</tt> code, control may not run |
| 321 | directly from a landing pad to the first catch. Control may actually flow |
| 322 | from the landing pad to clean up code and then to the first catch. Since the |
| 323 | required clean up for each <tt>invoke</tt> in a <tt>try</tt> may be different |
| 324 | (e.g. intervening constructor), there may be several landing pads for a given |
Jim Grosbach | 00484d1 | 2009-08-22 01:42:39 +0000 | [diff] [blame] | 325 | try. If cleanups need to be run, an <tt>i32 0</tt> should be passed as the |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 326 | last <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument. |
Jim Grosbach | 00484d1 | 2009-08-22 01:42:39 +0000 | [diff] [blame] | 327 | However, when using DWARF exception handling with C++, a <tt>i8* null</tt> |
| 328 | <a href="#restrictions">must</a> be passed instead.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 329 | |
| 330 | </div> |
| 331 | |
| 332 | <!-- ======================================================================= --> |
| 333 | <div class="doc_subsection"> |
| 334 | <a name="throw_filters">Throw Filters</a> |
| 335 | </div> |
| 336 | |
| 337 | <div class="doc_text"> |
| 338 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 339 | <p>C++ allows the specification of which exception types can be thrown from a |
| 340 | function. To represent this a top level landing pad may exist to filter out |
| 341 | invalid types. To express this in LLVM code the landing pad will |
| 342 | call <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The |
| 343 | arguments are a reference to the exception structure, a reference to the |
| 344 | personality function, the length of the filter expression (the number of type |
| 345 | infos plus one), followed by the type infos themselves. |
| 346 | <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> will return a |
| 347 | negative value if the exception does not match any of the type infos. If no |
| 348 | match is found then a call to <tt>__cxa_call_unexpected</tt> should be made, |
| 349 | otherwise <tt>_Unwind_Resume</tt>. Each of these functions requires a |
| 350 | reference to the exception structure. Note that the most general form of an |
| 351 | <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> call can contain |
| 352 | any number of type infos, filter expressions and cleanups (though having more |
| 353 | than one cleanup is pointless). The LLVM C++ front-end can generate such |
| 354 | <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls due to |
| 355 | inlining creating nested exception handling scopes.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 356 | |
| 357 | </div> |
| 358 | |
| 359 | <!-- ======================================================================= --> |
Duncan Sands | 6590b04 | 2007-08-27 15:47:50 +0000 | [diff] [blame] | 360 | <div class="doc_subsection"> |
| 361 | <a name="restrictions">Restrictions</a> |
| 362 | </div> |
| 363 | |
| 364 | <div class="doc_text"> |
| 365 | |
| 366 | <p>The semantics of the invoke instruction require that any exception that |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 367 | unwinds through an invoke call should result in a branch to the invoke's |
| 368 | unwind label. However such a branch will only happen if the |
| 369 | <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> matches. Thus in |
| 370 | order to ensure correct operation, the front-end must only generate |
| 371 | <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> calls that are |
| 372 | guaranteed to always match whatever exception unwinds through the invoke. |
| 373 | For most languages it is enough to pass zero, indicating the presence of |
| 374 | a <a href="#cleanups">cleanup</a>, as the |
| 375 | last <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> argument. |
| 376 | However for C++ this is not sufficient, because the C++ personality function |
| 377 | will terminate the program if it detects that unwinding the exception only |
| 378 | results in matches with cleanups. For C++ a <tt>null i8*</tt> should be |
| 379 | passed as the last <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> |
| 380 | argument instead. This is interpreted as a catch-all by the C++ personality |
| 381 | function, and will always match.</p> |
Duncan Sands | 6590b04 | 2007-08-27 15:47:50 +0000 | [diff] [blame] | 382 | |
| 383 | </div> |
| 384 | |
| 385 | <!-- ======================================================================= --> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 386 | <div class="doc_section"> |
Duncan Sands | 8036ca4 | 2007-03-30 12:22:09 +0000 | [diff] [blame] | 387 | <a name="format_common_intrinsics">Exception Handling Intrinsics</a> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 388 | </div> |
| 389 | |
| 390 | <div class="doc_text"> |
| 391 | |
| 392 | <p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 393 | provide exception handling information at various points in generated |
| 394 | code.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 395 | |
| 396 | </div> |
| 397 | |
| 398 | <!-- ======================================================================= --> |
| 399 | <div class="doc_subsubsection"> |
| 400 | <a name="llvm_eh_exception">llvm.eh.exception</a> |
| 401 | </div> |
| 402 | |
| 403 | <div class="doc_text"> |
Bill Wendling | 3cf4ffd | 2009-08-15 20:07:42 +0000 | [diff] [blame] | 404 | |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 405 | <pre> |
Bill Wendling | 3cf4ffd | 2009-08-15 20:07:42 +0000 | [diff] [blame] | 406 | i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>( ) |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 407 | </pre> |
| 408 | |
Duncan Sands | 6531d47 | 2008-12-29 15:27:32 +0000 | [diff] [blame] | 409 | <p>This intrinsic returns a pointer to the exception structure.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 410 | |
| 411 | </div> |
| 412 | |
| 413 | <!-- ======================================================================= --> |
| 414 | <div class="doc_subsubsection"> |
| 415 | <a name="llvm_eh_selector">llvm.eh.selector</a> |
| 416 | </div> |
| 417 | |
| 418 | <div class="doc_text"> |
Bill Wendling | 3cf4ffd | 2009-08-15 20:07:42 +0000 | [diff] [blame] | 419 | |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 420 | <pre> |
Duncan Sands | b01bbdc | 2009-10-14 16:11:37 +0000 | [diff] [blame] | 421 | i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, i8*, ...) |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 422 | </pre> |
| 423 | |
Duncan Sands | 6531d47 | 2008-12-29 15:27:32 +0000 | [diff] [blame] | 424 | <p>This intrinsic is used to compare the exception with the given type infos, |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 425 | filters and cleanups.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 426 | |
| 427 | <p><a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> takes a minimum of |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 428 | three arguments. The first argument is the reference to the exception |
| 429 | structure. The second argument is a reference to the personality function to |
| 430 | be used for this try catch sequence. Each of the remaining arguments is |
| 431 | either a reference to the type info for a catch statement, |
| 432 | a <a href="#throw_filters">filter</a> expression, or the number zero |
| 433 | representing a <a href="#cleanups">cleanup</a>. The exception is tested |
| 434 | against the arguments sequentially from first to last. The result of |
| 435 | the <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a> is a positive |
| 436 | number if the exception matched a type info, a negative number if it matched |
| 437 | a filter, and zero if it matched a cleanup. If nothing is matched, the |
| 438 | behaviour of the program is <a href="#restrictions">undefined</a>. If a type |
| 439 | info matched then the selector value is the index of the type info in the |
| 440 | exception table, which can be obtained using the |
| 441 | <a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 442 | |
| 443 | </div> |
| 444 | |
| 445 | <!-- ======================================================================= --> |
| 446 | <div class="doc_subsubsection"> |
| 447 | <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a> |
| 448 | </div> |
| 449 | |
| 450 | <div class="doc_text"> |
Bill Wendling | bf230bf | 2009-08-15 20:08:04 +0000 | [diff] [blame] | 451 | |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 452 | <pre> |
Duncan Sands | b01bbdc | 2009-10-14 16:11:37 +0000 | [diff] [blame] | 453 | i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*) |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 454 | </pre> |
| 455 | |
| 456 | <p>This intrinsic returns the type info index in the exception table of the |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 457 | current function. This value can be used to compare against the result |
| 458 | of <a href="#llvm_eh_selector"><tt>llvm.eh.selector</tt></a>. The single |
| 459 | argument is a reference to a type info.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 460 | |
| 461 | </div> |
| 462 | |
| 463 | <!-- ======================================================================= --> |
Jim Grosbach | f957012 | 2009-05-14 00:46:35 +0000 | [diff] [blame] | 464 | <div class="doc_subsubsection"> |
| 465 | <a name="llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a> |
| 466 | </div> |
| 467 | |
| 468 | <div class="doc_text"> |
Bill Wendling | 3cf4ffd | 2009-08-15 20:07:42 +0000 | [diff] [blame] | 469 | |
Jim Grosbach | f957012 | 2009-05-14 00:46:35 +0000 | [diff] [blame] | 470 | <pre> |
Bill Wendling | 3cf4ffd | 2009-08-15 20:07:42 +0000 | [diff] [blame] | 471 | i32 %<a href="#llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>(i8*) |
Jim Grosbach | f957012 | 2009-05-14 00:46:35 +0000 | [diff] [blame] | 472 | </pre> |
| 473 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 474 | <p>The SJLJ exception handling uses this intrinsic to force register saving for |
| 475 | the current function and to store the address of the following instruction |
| 476 | for use as a destination address by <a href="#llvm_eh_sjlj_longjmp"> |
| 477 | <tt>llvm.eh.sjlj.longjmp</tt></a>. The buffer format and the overall |
| 478 | functioning of this intrinsic is compatible with the GCC |
| 479 | <tt>__builtin_setjmp</tt> implementation, allowing code built with the |
| 480 | two compilers to interoperate.</p> |
Jim Grosbach | f957012 | 2009-05-14 00:46:35 +0000 | [diff] [blame] | 481 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 482 | <p>The single parameter is a pointer to a five word buffer in which the calling |
| 483 | context is saved. The front end places the frame pointer in the first word, |
| 484 | and the target implementation of this intrinsic should place the destination |
| 485 | address for a |
| 486 | <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> in the |
| 487 | second word. The following three words are available for use in a |
| 488 | target-specific manner.</p> |
Jim Grosbach | f957012 | 2009-05-14 00:46:35 +0000 | [diff] [blame] | 489 | |
Benjamin Kramer | e15192b | 2009-08-05 15:42:44 +0000 | [diff] [blame] | 490 | </div> |
| 491 | |
Jim Grosbach | f957012 | 2009-05-14 00:46:35 +0000 | [diff] [blame] | 492 | <!-- ======================================================================= --> |
Jim Grosbach | 1b747ad | 2009-08-11 00:09:57 +0000 | [diff] [blame] | 493 | <div class="doc_subsubsection"> |
| 494 | <a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a> |
| 495 | </div> |
| 496 | |
| 497 | <div class="doc_text"> |
Bill Wendling | 3cf4ffd | 2009-08-15 20:07:42 +0000 | [diff] [blame] | 498 | |
Jim Grosbach | 1b747ad | 2009-08-11 00:09:57 +0000 | [diff] [blame] | 499 | <pre> |
Bill Wendling | 3cf4ffd | 2009-08-15 20:07:42 +0000 | [diff] [blame] | 500 | i8* %<a href="#llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>( ) |
Jim Grosbach | 1b747ad | 2009-08-11 00:09:57 +0000 | [diff] [blame] | 501 | </pre> |
| 502 | |
| 503 | <p>Used for SJLJ based exception handling, the <a href="#llvm_eh_sjlj_lsda"> |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 504 | <tt>llvm.eh.sjlj.lsda</tt></a> intrinsic returns the address of the Language |
| 505 | Specific Data Area (LSDA) for the current function. The SJLJ front-end code |
| 506 | stores this address in the exception handling function context for use by the |
| 507 | runtime.</p> |
Jim Grosbach | 1b747ad | 2009-08-11 00:09:57 +0000 | [diff] [blame] | 508 | |
| 509 | </div> |
| 510 | |
| 511 | <!-- ======================================================================= --> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 512 | <div class="doc_section"> |
| 513 | <a name="asm">Asm Table Formats</a> |
| 514 | </div> |
| 515 | |
| 516 | <div class="doc_text"> |
| 517 | |
| 518 | <p>There are two tables that are used by the exception handling runtime to |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 519 | determine which actions should take place when an exception is thrown.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 520 | |
| 521 | </div> |
| 522 | |
| 523 | <!-- ======================================================================= --> |
| 524 | <div class="doc_subsection"> |
| 525 | <a name="unwind_tables">Exception Handling Frame</a> |
| 526 | </div> |
| 527 | |
| 528 | <div class="doc_text"> |
| 529 | |
| 530 | <p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 531 | frame used by dwarf debug info. The frame contains all the information |
| 532 | necessary to tear down the current frame and restore the state of the prior |
| 533 | frame. There is an exception handling frame for each function in a compile |
| 534 | unit, plus a common exception handling frame that defines information common |
| 535 | to all functions in the unit.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 536 | |
| 537 | <p>Todo - Table details here.</p> |
| 538 | |
| 539 | </div> |
| 540 | |
| 541 | <!-- ======================================================================= --> |
| 542 | <div class="doc_subsection"> |
| 543 | <a name="exception_tables">Exception Tables</a> |
| 544 | </div> |
| 545 | |
| 546 | <div class="doc_text"> |
| 547 | |
| 548 | <p>An exception table contains information about what actions to take when an |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 549 | exception is thrown in a particular part of a function's code. There is one |
| 550 | exception table per function except leaf routines and functions that have |
| 551 | only calls to non-throwing functions will not need an exception table.</p> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 552 | |
| 553 | <p>Todo - Table details here.</p> |
| 554 | |
| 555 | </div> |
| 556 | |
| 557 | <!-- ======================================================================= --> |
| 558 | <div class="doc_section"> |
| 559 | <a name="todo">ToDo</a> |
| 560 | </div> |
| 561 | |
| 562 | <div class="doc_text"> |
| 563 | |
| 564 | <ol> |
| 565 | |
Bill Wendling | c4f661e | 2009-08-15 08:56:09 +0000 | [diff] [blame] | 566 | <li>Testing/Testing/Testing.</li> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 567 | |
| 568 | </ol> |
| 569 | |
| 570 | </div> |
| 571 | |
| 572 | <!-- *********************************************************************** --> |
| 573 | |
| 574 | <hr> |
| 575 | <address> |
| 576 | <a href="http://jigsaw.w3.org/css-validator/check/referer"><img |
Misha Brukman | 4440870 | 2008-12-11 17:34:48 +0000 | [diff] [blame] | 577 | src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 578 | <a href="http://validator.w3.org/check/referer"><img |
Misha Brukman | 4440870 | 2008-12-11 17:34:48 +0000 | [diff] [blame] | 579 | src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> |
Jim Laskey | d0d39b6 | 2007-03-14 19:29:42 +0000 | [diff] [blame] | 580 | |
| 581 | <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> |
| 582 | <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> |
| 583 | Last modified: $Date$ |
| 584 | </address> |
| 585 | |
| 586 | </body> |
| 587 | </html> |