llvm.org GIT mirror llvm / 4a065dd
Update the EH doc to reflect the new EH model. This basically involved removing references to llvm.eh.exception, llvm.eh.selector, and llvm.eh.resume and replacing them with references to the landingpad and resume instructions. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@140128 91177308-0d34-0410-b5e6-96231b3b80d8 Bill Wendling 8 years ago
1 changed file(s) with 95 addition(s) and 195 deletion(s). Raw diff Collapse all Expand all
9595 Exception Handling. A description of the exception frame format can be
9696 found at
9797 Exception
98 Frames, with details of the DWARF 3 specification at
99 DWARF 3 Standard.
98 Frames, with details of the DWARF 4 specification at
99 DWARF 4 Standard.
100100 A description for the C++ exception table formats can be found at
101101 Exception Handling
102102 Tables.

115115 llvm.eh.sjlj.longjmp to
116116 handle control flow for exception handling.

117117
118

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.

118

For each function which does exception processing — be

119 it try/catch blocks or cleanups — that function
120 registers itself on a global frame list. When exceptions are unwinding, the
121 runtime uses this list to identify which functions need processing.

122122
123123

Landing pad selection is encoded in the call site entry of the function

124124 context. The runtime returns to the function via
133133 exceptions are thrown. As exceptions are, by their nature, intended for
134134 uncommon code paths, DWARF exception handling is generally preferred to
135135 SJLJ.

136
136137
137138
138139
175176 should take place. Actions typically pass control to a landing
176177 pad.

177178
178

A landing pad corresponds to the code found in the catch portion of

179 a try/catch sequence. When execution resumes at a landing
179

A landing pad corresponds to the code found in the catch portion of

180 a try/catch sequence. When execution resumes at a landing
180181 pad, it receives the exception structure and a selector corresponding to
181182 the type of exception thrown. The selector is then used to determine
182183 which catch should actually process the exception.

192193
193194
194195
195

At the time of this writing, only C++ exception handling support is available

196 in LLVM. So the remainder of this document will be somewhat C++-centric.

197
198196

From the C++ developers perspective, exceptions are defined in terms of the

199 throw and try/catch statements. In this section
197 throw and try/catch statements. In this section
200198 we will describe the implementation of LLVM exception handling in terms of
201199 C++ examples.

202200
209207
210208

Languages that support exception handling typically provide a throw

211209 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.

217
218

In C++, the allocation of the exception structure is done by

219 the __cxa_allocate_exception runtime function. The exception
220 raising is handled by __cxa_throw. The type of the exception is
221 represented using a C++ RTTI structure.

210 breaks down into two steps.

211
212
  • A request is made to allocate exception space for an exception structure.
  • 213 This structure needs to survive beyond the current activation. This
    214 structure will contain the type and value of the object being thrown.
    215
  • A call is made to the runtime to raise the exception, passing the
  • 216 exception structure as an argument.
    217
    218
    219

    In C++, the allocation of the exception structure is done by then

    220 __cxa_allocate_exception runtime function. The exception raising is
    221 handled by __cxa_throw. The type of the exception is represented
    222 using a C++ RTTI structure.

    222223
    223224
    224225
    243244 saves the exception structure reference and then proceeds to select the catch
    244245 block that corresponds to the type info of the exception object.

    245246
    246

    Two LLVM intrinsic functions are used to convey information about the landing

    247 pad to the back end.

    248
    249
    250
  • llvm.eh.exception takes no
  • 251 arguments and returns a pointer to the exception structure. This only
    252 returns a sensible value if called after an invoke has branched
    253 to a landing pad. Due to code generation limitations, it must currently
    254 be called in the landing pad itself.
    255
    256
  • llvm.eh.selector 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 try/catch sequence. Each of the
    260 remaining arguments is either a reference to the type info for
    261 a catch statement, a filter
    262 expression, or the number zero (0) representing
    263 a cleanup. The exception is tested against the
    264 arguments sequentially from first to last. The result of
    265 the llvm.eh.selector 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 undefined. This only returns a sensible
    270 value if called after an invoke 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 llvm.eh.typeid.for
    275 intrinsic.
    276 </ol>
    247 <p>The LLVM landingpad>
    248 instruction is used to convey information about the landing pad to the
    249 back end. For C++, the landingpad instruction returns a pointer and
    250 integer pair corresponding to the pointer to the exception structure and the
    251 "selector value" respectively.

    252
    253

    The landingpad instruction takes a reference to the personality

    254 function to be used for this try/catch sequence. The
    255 remainder of the instruction is a list of catch and filter
    256 clauses. The exception is tested against the clauses sequentially from first
    257 to last. The selector value is a positive number if the exception matched a
    258 type info, a negative number if it matched a filter, and zero if it matched a
    259 cleanup. If nothing is matched, the behaviour of the program
    260 is undefined. If a type info matched, then the
    261 selector value is the index of the type info in the exception table, which
    262 can be obtained using the
    263 llvm.eh.typeid.for intrinsic.

    277264
    278265

    Once the landing pad has the type info selector, the code branches to the

    279 code for the first catch. The catch then checks the value of the type info
    266 code for the first catch. The catch then checks the value of the type info
    280267 selector against the index of type info for that catch. Since the type info
    281268 index is not known until all the type info have been gathered in the backend,
    282269 the catch code will call the
    283 llvm.eh.typeid.for 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 llvm.eh.selector, then
    288 neither the last catch nor catch all need to perform the check
    289 against the selector.

    270 llvm.eh.typeid.for intrinsic to
    271 determine the index for a given type info. If the catch fails to match the
    272 selector then control is passed on to the next catch. Note: Since the landing
    273 pad will not be used if there is no match in the list of type info on the
    274 call to the landingpad
    275 instruction, then neither the last catch nor catch all need to
    276 perform the check against the selector.

    290277
    291278

    Finally, the entry and exit of catch code is bracketed with calls

    292279 to __cxa_begin_catch and __cxa_end_catch.

    317304
    318305
    319306
    320

    A cleanup is extra code which needs to be run as part of unwinding

    321 a scope. C++ destructors are a prominent example, but other
    322 languages and language extensions provide a variety of different
    323 kinds of cleanup. In general, a landing pad may need to run
    324 arbitrary amounts of cleanup code before actually entering a catch
    325 block. To indicate the presence of cleanups, a landing pad's call
    326 to llvm.eh.selector should
    327 end with the argument i32 0; otherwise, the unwinder will
    328 not stop at the landing pad if there are no catches or filters that
    329 require it to.

    307

    A cleanup is extra code which needs to be run as part of unwinding a scope.

    308 C++ destructors are a prominent example, but other languages and language
    309 extensions provide a variety of different kinds of cleanup. In general, a
    310 landing pad may need to run arbitrary amounts of cleanup code before actually
    311 entering a catch block. To indicate the presence of cleanups, a
    312 landingpad instruction
    313 should have a cleanup clause. Otherwise, the unwinder will not stop at
    314 the landing pad if there are no catches or filters that require it to.

    330315
    331316

    Do not allow a new exception to propagate out of the execution of a

    332317 cleanup. This can corrupt the internal state of the unwinder.
    336321
    337322

    When all cleanups have completed, if the exception is not handled

    338323 by the current function, resume unwinding by calling the
    339 llvm.eh.resume intrinsic,
    340 passing in the results of llvm.eh.exception and
    341 <tt>llvm.eh.selector for the original landing pad.

    324 <a href="LangRef.html#i_resume">resume instruction, passing in
    325 the results of the landingpad instruction for the original landing
    326 pad.

    342327
    343328
    344329
    351336
    352337

    C++ allows the specification of which exception types can be thrown from a

    353338 function. To represent this a top level landing pad may exist to filter out
    354 invalid types. To express this in LLVM code the landing pad will
    355 call llvm.eh.selector. The
    356 arguments are a reference to the exception structure, a reference to the
    357 personality function, the length of the filter expression (the number of type
    358 infos plus one), followed by the type infos themselves.
    359 llvm.eh.selector will return a
    360 negative value if the exception does not match any of the type infos. If no
    361 match is found then a call to __cxa_call_unexpected should be made,
    362 otherwise _Unwind_Resume. Each of these functions requires a
    363 reference to the exception structure. Note that the most general form of an
    364 llvm.eh.selector call can contain
    365 any number of type infos, filter expressions and cleanups (though having more
    366 than one cleanup is pointless). The LLVM C++ front-end can generate such
    367 llvm.eh.selector calls due to
    368 inlining creating nested exception handling scopes.

    339 invalid types. To express this in LLVM code the
    340 landingpad instruction will
    341 have a filter clause. The clause consists of an array of type infos.
    342 landingpad will return a negative value if the exception does not
    343 match any of the type infos. If no match is found then a call
    344 to __cxa_call_unexpected should be made, otherwise
    345 _Unwind_Resume. Each of these functions requires a reference to the
    346 exception structure. Note that the most general form of a
    347 landingpad instruction can
    348 have any number of catch, cleanup, and filter clauses (though having more
    349 than one cleanup is pointless). The LLVM C++ front-end can generate such
    350 landingpad instructions due
    351 to inlining creating nested exception handling scopes.

    369352
    370353
    371354
    376359
    377360
    378361
    379

    The unwinder delegates the decision of whether to stop in a call

    380 frame to that call frame's language-specific personality function.
    381 Not all personalities functions guarantee that they will stop to
    382 perform cleanups: for example, the GNU C++ personality doesn't do
    383 so unless the exception is actually caught somewhere further up the
    384 stack. When using this personality to implement EH for a language
    385 that guarantees that cleanups will always be run, be sure to
    386 indicate a catch-all in the
    387 llvm.eh.selector call
    362

    The unwinder delegates the decision of whether to stop in a call frame to

    363 that call frame's language-specific personality function. Not all
    364 personalities functions guarantee that they will stop to perform
    365 cleanups. For example, the GNU C++ personality doesn't do so unless the
    366 exception is actually caught somewhere further up the stack. When using this
    367 personality to implement EH for a language that guarantees that cleanups will
    368 always be run, be sure to indicate a catch-all in the
    369 landingpad instruction
    388370 rather than just cleanups.

    389371
    390

    In order for inlining to behave correctly, landing pads must be

    391 prepared to handle selector results that they did not originally
    392 advertise. Suppose that a function catches exceptions of
    393 type A, and it's inlined into a function that catches
    394 exceptions of type B. The inliner will update the
    395 selector for the inlined landing pad to include the fact
    396 that B is caught. If that landing pad assumes that it
    397 will only be entered to catch an A, it's in for a rude
    398 surprise. Consequently, landing pads must test for the selector
    399 results they understand and then resume exception propagation
    400 with the llvm.eh.resume
    401 intrinsic if none of the conditions match.

    372

    In order for inlining to behave correctly, landing pads must be prepared to

    373 handle selector results that they did not originally advertise. Suppose that
    374 a function catches exceptions of type A, and it's inlined into a
    375 function that catches exceptions of type B. The inliner will update
    376 the landingpad instruction for the inlined landing pad to include
    377 the fact that B is caught. If that landing pad assumes that it will
    378 only be entered to catch an A, it's in for a rude surprise.
    379 Consequently, landing pads must test for the selector results they understand
    380 and then resume exception propagation with the
    381 resume instruction if none of
    382 the conditions match.

    402383
    403384
    404385
    411392
    412393
    413394
    414

    LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to

    395

    In addition to the

    396 landingpad and
    397 resume instructions, LLVM uses
    398 several intrinsic functions (name prefixed with "llvm.eh") to
    415399 provide exception handling information at various points in generated
    416400 code.

    417
    418
    419

    420 llvm.eh.exception
    421
    422
    423
    424
    425
    
                      
                    
    426 i8* %llvm.eh.exception()
    427
    428
    429

    This intrinsic returns a pointer to the exception structure.

    430
    431
    432
    433
    434

    435 llvm.eh.selector
    436
    437
    438
    439
    440
    
                      
                    
    441 i32 %llvm.eh.selector(i8*, i8*, ...)
    442
    443
    444

    This intrinsic is used to compare the exception with the given type infos,

    445 filters and cleanups.

    446
    447

    llvm.eh.selector takes a

    448 minimum of three arguments. The first argument is the reference to
    449 the exception structure. The second argument is a reference to the
    450 personality function to be used for this try catch sequence. Each
    451 of the remaining arguments is either a reference to the type info
    452 for a catch statement, a filter
    453 expression, or the number zero representing
    454 a cleanup. The exception is tested against
    455 the arguments sequentially from first to last. The result of
    456 the llvm.eh.selector is a
    457 positive number if the exception matched a type info, a negative
    458 number if it matched a filter, and zero if it matched a cleanup.
    459 If nothing is matched, or if only a cleanup is matched, different
    460 personality functions may or may not cause control to stop at the
    461 landing pad; see the restrictions for
    462 more information. If a type info matched then the selector value
    463 is the index of the type info in the exception table, which can be
    464 obtained using the
    465 llvm.eh.typeid.for intrinsic.

    466
    467

    If a landing pad containing a call to llvm.eh.selector is

    468 inlined into an invoke instruction, the selector arguments
    469 for the outer landing pad are appended to those of the inlined
    470 landing pad. Consequently, landing pads must be written to ignore
    471 selector values that they did not originally advertise.

    472
    473
    474401
    475402
    476403

    487414 current function. This value can be used to compare against the result
    488415 of llvm.eh.selector. The single
    489416 argument is a reference to a type info.

    490
    491
    492
    493
    494

    495 llvm.eh.resume
    496
    497
    498
    499
    500
    
                      
                    
    501 void %llvm.eh.resume(i8*, i32) noreturn
    502
    503
    504

    This intrinsic is used to resume propagation of an exception after

    505 landing at a landing pad. The first argument should be the result
    506 of llvm.eh.exception for that
    507 landing pad, and the second argument should be the result of
    508 llvm.eh.selector. When a call to
    509 this intrinsic is inlined into an invoke, the call is transformed
    510 into a branch to the invoke's unwind destination, using its
    511 arguments in place of the calls
    512 to llvm.eh.exception and
    513 llvm.eh.selector there.

    514
    515

    This intrinsic is not implicitly nounwind; calls to it

    516 will always throw. It may not be invoked.

    517417
    518418
    519419