llvm.org GIT mirror llvm / 7d85f87
Sphinxify the exception handling doc. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@159254 91177308-0d34-0410-b5e6-96231b3b80d8 Bill Wendling 7 years ago
3 changed file(s) with 369 addition(s) and 564 deletion(s). Raw diff Collapse all Expand all
+0
-563
docs/ExceptionHandling.html less more
None
1 "http://www.w3.org/TR/html4/strict.dtd">
2
3
4 Exception Handling in LLVM
5
6
7 content="Exception Handling in LLVM.">
8
9
10
11
12
13

Exception Handling in LLVM

14
15
16
17
18
19
  • Introduction
  • 20
    21
  • Itanium ABI Zero-cost Exception Handling
  • 22
  • Setjmp/Longjmp Exception Handling
  • 23
  • Overview
  • 24
    25
  • LLVM Code Generation
  • 26
    27
  • Throw
  • 28
  • Try/Catch
  • 29
  • Cleanups
  • 30
  • Throw Filters
  • 31
  • Restrictions
  • 32
    33
  • Exception Handling Intrinsics
  • 34
    35
  • llvm.eh.typeid.for
  • 36
  • llvm.eh.sjlj.setjmp
  • 37
  • llvm.eh.sjlj.longjmp
  • 38
  • llvm.eh.sjlj.lsda
  • 39
  • llvm.eh.sjlj.callsite
  • 40
    41
  • Asm Table Formats
  • 42
    43
  • Exception Handling Frame
  • 44
  • Exception Tables
  • 45
    46
    47
    48
    49
    50
    51

    Written by the LLVM Team

    52
    53
    54
    55
    56

    Introduction

    57
    58
    59
    60
    61

    This document is the central repository for all information pertaining to

    62 exception handling in LLVM. It describes the format that LLVM exception
    63 handling information takes, which is useful for those interested in creating
    64 front-ends or dealing directly with the information. Further, this document
    65 provides specific examples of what exception handling information is used for
    66 in C and C++.

    67
    68
    69

    70 Itanium ABI Zero-cost Exception Handling
    71
    72
    73
    74
    75

    Exception handling for most programming languages is designed to recover from

    76 conditions that rarely occur during general use of an application. To that
    77 end, exception handling should not interfere with the main flow of an
    78 application's algorithm by performing checkpointing tasks, such as saving the
    79 current pc or register state.

    80
    81

    The Itanium ABI Exception Handling Specification defines a methodology for

    82 providing outlying data in the form of exception tables without inlining
    83 speculative exception handling code in the flow of an application's main
    84 algorithm. Thus, the specification is said to add "zero-cost" to the normal
    85 execution of an application.

    86
    87

    A more complete description of the Itanium ABI exception handling runtime

    88 support of can be found at
    89 Itanium C++ ABI:
    90 Exception Handling. A description of the exception frame format can be
    91 found at
    92 Exception
    93 Frames, with details of the DWARF 4 specification at
    94 DWARF 4 Standard.
    95 A description for the C++ exception table formats can be found at
    96 Exception Handling
    97 Tables.

    98
    99
    100
    101
    102

    103 Setjmp/Longjmp Exception Handling
    104
    105
    106
    107
    108

    Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics

    109 llvm.eh.sjlj.setjmp and
    110 llvm.eh.sjlj.longjmp to
    111 handle control flow for exception handling.

    112
    113

    For each function which does exception processing — be

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

    117
    118

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

    119 context. The runtime returns to the function via
    120 llvm.eh.sjlj.longjmp, where
    121 a switch table transfers control to the appropriate landing pad based on
    122 the index stored in the function context.

    123
    124

    In contrast to DWARF exception handling, which encodes exception regions

    125 and frame information in out-of-line tables, SJLJ exception handling
    126 builds and removes the unwind frame context at runtime. This results in
    127 faster exception handling at the expense of slower execution when no
    128 exceptions are thrown. As exceptions are, by their nature, intended for
    129 uncommon code paths, DWARF exception handling is generally preferred to
    130 SJLJ.

    131
    132
    133
    134
    135

    136 Overview
    137
    138
    139
    140
    141

    When an exception is thrown in LLVM code, the runtime does its best to find a

    142 handler suited to processing the circumstance.

    143
    144

    The runtime first attempts to find an exception frame corresponding to

    145 the function where the exception was thrown. If the programming language
    146 supports exception handling (e.g. C++), the exception frame contains a
    147 reference to an exception table describing how to process the exception. If
    148 the language does not support exception handling (e.g. C), or if the
    149 exception needs to be forwarded to a prior activation, the exception frame
    150 contains information about how to unwind the current activation and restore
    151 the state of the prior activation. This process is repeated until the
    152 exception is handled. If the exception is not handled and no activations
    153 remain, then the application is terminated with an appropriate error
    154 message.

    155
    156

    Because different programming languages have different behaviors when

    157 handling exceptions, the exception handling ABI provides a mechanism for
    158 supplying personalities. An exception handling personality is defined
    159 by way of a personality function (e.g. __gxx_personality_v0
    160 in C++), which receives the context of the exception, an exception
    161 structure containing the exception object type and value, and a reference
    162 to the exception table for the current function. The personality function
    163 for the current compile unit is specified in a common exception
    164 frame.

    165
    166

    The organization of an exception table is language dependent. For C++, an

    167 exception table is organized as a series of code ranges defining what to do
    168 if an exception occurs in that range. Typically, the information associated
    169 with a range defines which types of exception objects (using C++ type
    170 info) that are handled in that range, and an associated action that
    171 should take place. Actions typically pass control to a landing
    172 pad.

    173
    174

    A landing pad corresponds roughly to the code found in the catch

    175 portion of a try/catch sequence. When execution resumes at
    176 a landing pad, it receives an exception structure and a
    177 selector value corresponding to the type of exception
    178 thrown. The selector is then used to determine which catch should
    179 actually process the exception.

    180
    181
    182
    183
    184
    185
    186

    187 LLVM Code Generation
    188
    189
    190
    191
    192

    From a C++ developer's perspective, exceptions are defined in terms of the

    193 throw and try/catch statements. In this section
    194 we will describe the implementation of LLVM exception handling in terms of
    195 C++ examples.

    196
    197
    198

    199 Throw
    200
    201
    202
    203
    204

    Languages that support exception handling typically provide a throw

    205 operation to initiate the exception process. Internally, a throw
    206 operation breaks down into two steps.

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

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

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

    221
    222
    223
    224
    225

    226 Try/Catch
    227
    228
    229
    230
    231

    A call within the scope of a try statement can potentially raise an

    232 exception. In those circumstances, the LLVM C++ front-end replaces the call
    233 with an invoke instruction. Unlike a call, the invoke has
    234 two potential continuation points:

    235
    236
    237
  • where to continue when the call succeeds as per normal, and
  • 238
    239
  • where to continue if the call raises an exception, either by a throw or
  • 240 the unwinding of a throw
    241
    242
    243

    The term used to define a the place where an invoke continues after

    244 an exception is called a landing pad. LLVM landing pads are
    245 conceptually alternative function entry points where an exception structure
    246 reference and a type info index are passed in as arguments. The landing pad
    247 saves the exception structure reference and then proceeds to select the catch
    248 block that corresponds to the type info of the exception object.

    249
    250

    The LLVM landingpad

    251 instruction is used to convey information about the landing pad to the
    252 back end. For C++, the landingpad instruction returns a pointer and
    253 integer pair corresponding to the pointer to the exception structure
    254 and the selector value respectively.

    255
    256

    The landingpad instruction takes a reference to the personality

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

    267
    268

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

    269 code for the first catch. The catch then checks the value of the type info
    270 selector against the index of type info for that catch. Since the type info
    271 index is not known until all the type infos have been gathered in the
    272 backend, the catch code must call the
    273 llvm.eh.typeid.for intrinsic to
    274 determine the index for a given type info. If the catch fails to match the
    275 selector then control is passed on to the next catch.

    276
    277

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

    278 __cxa_begin_catch and __cxa_end_catch.

    279
    280
    281
  • __cxa_begin_catch takes an exception structure reference as an
  • 282 argument and returns the value of the exception object.
    283
    284
  • __cxa_end_catch takes no arguments. This function:

  • 285
    286
  • Locates the most recently caught exception and decrements its handler
  • 287 count,
    288
  • Removes the exception from the caught stack if the handler
  • 289 count goes to zero, and
    290
  • Destroys the exception if the handler count goes to zero and the
  • 291 exception was not re-thrown by throw.
    292
    293

    Note: a rethrow from within the catch may replace this call with

    294 a __cxa_rethrow.

    295
    296
    297
    298
    299
    300

    301 Cleanups
    302
    303
    304
    305
    306

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

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

    314
    315

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

    316 of a cleanup. This can corrupt the internal state of the unwinder.
    317 Different languages describe different high-level semantics for these
    318 situations: for example, C++ requires that the process be terminated, whereas
    319 Ada cancels both exceptions and throws a third.

    320
    321

    When all cleanups are finished, if the exception is not handled by the

    322 current function, resume unwinding by calling the
    323 resume instruction, passing in
    324 the result of the landingpad instruction for the original landing
    325 pad.

    326
    327
    328
    329
    330

    331 Throw Filters
    332
    333
    334
    335
    336

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

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

    351
    352
    353
    354
    355

    356 Restrictions
    357
    358
    359
    360
    361

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

    362 that call frame's language-specific personality function. Not all unwinders
    363 guarantee that they will stop to perform cleanups. For example, the GNU C++
    364 unwinder doesn't do so unless the exception is actually caught somewhere
    365 further up the stack.

    366
    367

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

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

    378
    379
    380
    381
    382
    383
    384

    385 Exception Handling Intrinsics
    386
    387
    388
    389
    390

    In addition to the

    391 landingpad and
    392 resume instructions, LLVM uses
    393 several intrinsic functions (name prefixed with llvm.eh) to
    394 provide exception handling information at various points in generated
    395 code.

    396
    397
    398

    399 llvm.eh.typeid.for
    400
    401
    402
    403
    404
    
                      
                    
    405 i32 @llvm.eh.typeid.for(i8* %type_info)
    406
    407
    408

    This intrinsic returns the type info index in the exception table of the

    409 current function. This value can be used to compare against the result
    410 of landingpad instruction.
    411 The single argument is a reference to a type info.

    412
    413
    414
    415
    416

    417 llvm.eh.sjlj.setjmp
    418
    419
    420
    421
    422
    
                      
                    
    423 i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
    424
    425
    426

    For SJLJ based exception handling, this intrinsic forces register saving for

    427 the current function and stores the address of the following instruction for
    428 use as a destination address
    429 by llvm.eh.sjlj.longjmp. The
    430 buffer format and the overall functioning of this intrinsic is compatible
    431 with the GCC __builtin_setjmp implementation allowing code built
    432 with the clang and GCC to interoperate.

    433
    434

    The single parameter is a pointer to a five word buffer in which the calling

    435 context is saved. The front end places the frame pointer in the first word,
    436 and the target implementation of this intrinsic should place the destination
    437 address for a
    438 llvm.eh.sjlj.longjmp in the
    439 second word. The following three words are available for use in a
    440 target-specific manner.

    441
    442
    443
    444
    445

    446 llvm.eh.sjlj.longjmp
    447
    448
    449
    450
    451
    
                      
                    
    452 void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
    453
    454
    455

    For SJLJ based exception handling, the llvm.eh.sjlj.longjmp

    456 intrinsic is used to implement __builtin_longjmp(). The single
    457 parameter is a pointer to a buffer populated
    458 by llvm.eh.sjlj.setjmp. The frame
    459 pointer and stack pointer are restored from the buffer, then control is
    460 transferred to the destination address.

    461
    462
    463
    464

    465 llvm.eh.sjlj.lsda
    466
    467
    468
    469
    470
    
                      
                    
    471 i8* @llvm.eh.sjlj.lsda()
    472
    473
    474

    For SJLJ based exception handling, the llvm.eh.sjlj.lsda intrinsic

    475 returns the address of the Language Specific Data Area (LSDA) for the current
    476 function. The SJLJ front-end code stores this address in the exception
    477 handling function context for use by the runtime.

    478
    479
    480
    481
    482

    483 llvm.eh.sjlj.callsite
    484
    485
    486
    487
    488
    
                      
                    
    489 void @llvm.eh.sjlj.callsite(i32 %call_site_num)
    490
    491
    492

    For SJLJ based exception handling, the llvm.eh.sjlj.callsite

    493 intrinsic identifies the callsite value associated with the
    494 following invoke instruction. This is used to ensure that landing
    495 pad entries in the LSDA are generated in matching order.

    496
    497
    498
    499
    500
    501
    502

    503 Asm Table Formats
    504
    505
    506
    507
    508

    There are two tables that are used by the exception handling runtime to

    509 determine which actions should be taken when an exception is thrown.

    510
    511
    512

    513 Exception Handling Frame
    514
    515
    516
    517
    518

    An exception handling frame eh_frame is very similar to the unwind

    519 frame used by DWARF debug info. The frame contains all the information
    520 necessary to tear down the current frame and restore the state of the prior
    521 frame. There is an exception handling frame for each function in a compile
    522 unit, plus a common exception handling frame that defines information common
    523 to all functions in the unit.

    524
    525
    526
    527
    528
    529
    530

    531 Exception Tables
    532
    533
    534
    535
    536

    An exception table contains information about what actions to take when an

    537 exception is thrown in a particular part of a function's code. There is one
    538 exception table per function, except leaf functions and functions that have
    539 calls only to non-throwing functions. They do not need an exception
    540 table.

    541
    542
    543
    544
    545
    546
    547
    548
    549
    550
    551
    552
    553 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS">
    554
    555 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01">
    556
    557 LLVM Compiler Infrastructure
    558 Last modified: $Date$
    559
    560
    561
    562
    0 .. _exception_handling:
    1
    2 ==========================
    3 Exception Handling in LLVM
    4 ==========================
    5
    6 .. contents::
    7 :local:
    8
    9 Introduction
    10 ============
    11
    12 This document is the central repository for all information pertaining to
    13 exception handling in LLVM. It describes the format that LLVM exception
    14 handling information takes, which is useful for those interested in creating
    15 front-ends or dealing directly with the information. Further, this document
    16 provides specific examples of what exception handling information is used for in
    17 C and C++.
    18
    19 Itanium ABI Zero-cost Exception Handling
    20 ----------------------------------------
    21
    22 Exception handling for most programming languages is designed to recover from
    23 conditions that rarely occur during general use of an application. To that end,
    24 exception handling should not interfere with the main flow of an application's
    25 algorithm by performing checkpointing tasks, such as saving the current pc or
    26 register state.
    27
    28 The Itanium ABI Exception Handling Specification defines a methodology for
    29 providing outlying data in the form of exception tables without inlining
    30 speculative exception handling code in the flow of an application's main
    31 algorithm. Thus, the specification is said to add "zero-cost" to the normal
    32 execution of an application.
    33
    34 A more complete description of the Itanium ABI exception handling runtime
    35 support of can be found at `Itanium C++ ABI: Exception Handling
    36 `_. A description of the
    37 exception frame format can be found at `Exception Frames
    38 `_,
    39 with details of the DWARF 4 specification at `DWARF 4 Standard
    40 `_. A description for the C++ exception
    41 table formats can be found at `Exception Handling Tables
    42 `_.
    43
    44 Setjmp/Longjmp Exception Handling
    45 ---------------------------------
    46
    47 Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
    48 `llvm.eh.sjlj.setjmp`_ and `llvm.eh.sjlj.longjmp`_ to handle control flow for
    49 exception handling.
    50
    51 For each function which does exception processing --- be it ``try``/``catch``
    52 blocks or cleanups --- that function registers itself on a global frame
    53 list. When exceptions are unwinding, the runtime uses this list to identify
    54 which functions need processing.
    55
    56 Landing pad selection is encoded in the call site entry of the function
    57 context. The runtime returns to the function via `llvm.eh.sjlj.longjmp`_, where
    58 a switch table transfers control to the appropriate landing pad based on the
    59 index stored in the function context.
    60
    61 In contrast to DWARF exception handling, which encodes exception regions and
    62 frame information in out-of-line tables, SJLJ exception handling builds and
    63 removes the unwind frame context at runtime. This results in faster exception
    64 handling at the expense of slower execution when no exceptions are thrown. As
    65 exceptions are, by their nature, intended for uncommon code paths, DWARF
    66 exception handling is generally preferred to SJLJ.
    67
    68 Overview
    69 --------
    70
    71 When an exception is thrown in LLVM code, the runtime does its best to find a
    72 handler suited to processing the circumstance.
    73
    74 The runtime first attempts to find an *exception frame* corresponding to the
    75 function where the exception was thrown. If the programming language supports
    76 exception handling (e.g. C++), the exception frame contains a reference to an
    77 exception table describing how to process the exception. If the language does
    78 not support exception handling (e.g. C), or if the exception needs to be
    79 forwarded to a prior activation, the exception frame contains information about
    80 how to unwind the current activation and restore the state of the prior
    81 activation. This process is repeated until the exception is handled. If the
    82 exception is not handled and no activations remain, then the application is
    83 terminated with an appropriate error message.
    84
    85 Because different programming languages have different behaviors when handling
    86 exceptions, the exception handling ABI provides a mechanism for
    87 supplying *personalities*. An exception handling personality is defined by
    88 way of a *personality function* (e.g. ``__gxx_personality_v0`` in C++),
    89 which receives the context of the exception, an *exception structure*
    90 containing the exception object type and value, and a reference to the exception
    91 table for the current function. The personality function for the current
    92 compile unit is specified in a *common exception frame*.
    93
    94 The organization of an exception table is language dependent. For C++, an
    95 exception table is organized as a series of code ranges defining what to do if
    96 an exception occurs in that range. Typically, the information associated with a
    97 range defines which types of exception objects (using C++ *type info*) that are
    98 handled in that range, and an associated action that should take place. Actions
    99 typically pass control to a *landing pad*.
    100
    101 A landing pad corresponds roughly to the code found in the ``catch`` portion of
    102 a ``try``/``catch`` sequence. When execution resumes at a landing pad, it
    103 receives an *exception structure* and a *selector value* corresponding to the
    104 *type* of exception thrown. The selector is then used to determine which *catch*
    105 should actually process the exception.
    106
    107 LLVM Code Generation
    108 ====================
    109
    110 From a C++ developer's perspective, exceptions are defined in terms of the
    111 ``throw`` and ``try``/``catch`` statements. In this section we will describe the
    112 implementation of LLVM exception handling in terms of C++ examples.
    113
    114 Throw
    115 -----
    116
    117 Languages that support exception handling typically provide a ``throw``
    118 operation to initiate the exception process. Internally, a ``throw`` operation
    119 breaks down into two steps.
    120
    121 #. A request is made to allocate exception space for an exception structure.
    122 This structure needs to survive beyond the current activation. This structure
    123 will contain the type and value of the object being thrown.
    124
    125 #. A call is made to the runtime to raise the exception, passing the exception
    126 structure as an argument.
    127
    128 In C++, the allocation of the exception structure is done by the
    129 ``__cxa_allocate_exception`` runtime function. The exception raising is handled
    130 by ``__cxa_throw``. The type of the exception is represented using a C++ RTTI
    131 structure.
    132
    133 Try/Catch
    134 ---------
    135
    136 A call within the scope of a *try* statement can potentially raise an
    137 exception. In those circumstances, the LLVM C++ front-end replaces the call with
    138 an ``invoke`` instruction. Unlike a call, the ``invoke`` has two potential
    139 continuation points:
    140
    141 #. where to continue when the call succeeds as per normal, and
    142
    143 #. where to continue if the call raises an exception, either by a throw or the
    144 unwinding of a throw
    145
    146 The term used to define a the place where an ``invoke`` continues after an
    147 exception is called a *landing pad*. LLVM landing pads are conceptually
    148 alternative function entry points where an exception structure reference and a
    149 type info index are passed in as arguments. The landing pad saves the exception
    150 structure reference and then proceeds to select the catch block that corresponds
    151 to the type info of the exception object.
    152
    153 The LLVM `landingpad instruction `_ is used to convey
    154 information about the landing pad to the back end. For C++, the ``landingpad``
    155 instruction returns a pointer and integer pair corresponding to the pointer to
    156 the *exception structure* and the *selector value* respectively.
    157
    158 The ``landingpad`` instruction takes a reference to the personality function to
    159 be used for this ``try``/``catch`` sequence. The remainder of the instruction is
    160 a list of *cleanup*, *catch*, and *filter* clauses. The exception is tested
    161 against the clauses sequentially from first to last. The selector value is a
    162 positive number if the exception matched a type info, a negative number if it
    163 matched a filter, and zero if it matched a cleanup. If nothing is matched, the
    164 behavior of the program is `undefined`_. If a type info matched, then the
    165 selector value is the index of the type info in the exception table, which can
    166 be obtained using the `llvm.eh.typeid.for`_ intrinsic.
    167
    168 Once the landing pad has the type info selector, the code branches to the code
    169 for the first catch. The catch then checks the value of the type info selector
    170 against the index of type info for that catch. Since the type info index is not
    171 known until all the type infos have been gathered in the backend, the catch code
    172 must call the `llvm.eh.typeid.for`_ intrinsic to determine the index for a given
    173 type info. If the catch fails to match the selector then control is passed on to
    174 the next catch.
    175
    176 Finally, the entry and exit of catch code is bracketed with calls to
    177 ``__cxa_begin_catch`` and ``__cxa_end_catch``.
    178
    179 * ``__cxa_begin_catch`` takes an exception structure reference as an argument
    180 and returns the value of the exception object.
    181
    182 * ``__cxa_end_catch`` takes no arguments. This function:
    183
    184 #. Locates the most recently caught exception and decrements its handler
    185 count,
    186
    187 #. Removes the exception from the *caught* stack if the handler count goes to
    188 zero, and
    189
    190 #. Destroys the exception if the handler count goes to zero and the exception
    191 was not re-thrown by throw.
    192
    193 .. note::
    194
    195 a rethrow from within the catch may replace this call with a
    196 ``__cxa_rethrow``.
    197
    198 Cleanups
    199 --------
    200
    201 A cleanup is extra code which needs to be run as part of unwinding a scope. C++
    202 destructors are a typical example, but other languages and language extensions
    203 provide a variety of different kinds of cleanups. In general, a landing pad may
    204 need to run arbitrary amounts of cleanup code before actually entering a catch
    205 block. To indicate the presence of cleanups, a `landingpad
    206 instruction `_ should have a *cleanup*
    207 clause. Otherwise, the unwinder will not stop at the landing pad if there are no
    208 catches or filters that require it to.
    209
    210 .. note::
    211
    212 Do not allow a new exception to propagate out of the execution of a
    213 cleanup. This can corrupt the internal state of the unwinder. Different
    214 languages describe different high-level semantics for these situations: for
    215 example, C++ requires that the process be terminated, whereas Ada cancels both
    216 exceptions and throws a third.
    217
    218 When all cleanups are finished, if the exception is not handled by the current
    219 function, resume unwinding by calling the `resume
    220 instruction `_, passing in the result of the
    221 ``landingpad`` instruction for the original landing pad.
    222
    223 Throw Filters
    224 -------------
    225
    226 C++ allows the specification of which exception types may be thrown from a
    227 function. To represent this, a top level landing pad may exist to filter out
    228 invalid types. To express this in LLVM code the `landingpad
    229 instruction `_ will have a filter clause. The clause
    230 consists of an array of type infos. ``landingpad`` will return a negative value
    231 if the exception does not match any of the type infos. If no match is found then
    232 a call to ``__cxa_call_unexpected`` should be made, otherwise
    233 ``_Unwind_Resume``. Each of these functions requires a reference to the
    234 exception structure. Note that the most general form of a ``landingpad``
    235 instruction can have any number of catch, cleanup, and filter clauses (though
    236 having more than one cleanup is pointless). The LLVM C++ front-end can generate
    237 such ``landingpad`` instructions due to inlining creating nested exception
    238 handling scopes.
    239
    240 .. _undefined:
    241
    242 Restrictions
    243 ------------
    244
    245 The unwinder delegates the decision of whether to stop in a call frame to that
    246 call frame's language-specific personality function. Not all unwinders guarantee
    247 that they will stop to perform cleanups. For example, the GNU C++ unwinder
    248 doesn't do so unless the exception is actually caught somewhere further up the
    249 stack.
    250
    251 In order for inlining to behave correctly, landing pads must be prepared to
    252 handle selector results that they did not originally advertise. Suppose that a
    253 function catches exceptions of type ``A``, and it's inlined into a function that
    254 catches exceptions of type ``B``. The inliner will update the ``landingpad``
    255 instruction for the inlined landing pad to include the fact that ``B`` is also
    256 caught. If that landing pad assumes that it will only be entered to catch an
    257 ``A``, it's in for a rude awakening. Consequently, landing pads must test for
    258 the selector results they understand and then resume exception propagation with
    259 the `resume instruction `_ if none of the conditions
    260 match.
    261
    262 Exception Handling Intrinsics
    263 =============================
    264
    265 In addition to the ``landingpad`` and ``resume`` instructions, LLVM uses several
    266 intrinsic functions (name prefixed with ``llvm.eh``) to provide exception
    267 handling information at various points in generated code.
    268
    269 .. _llvm.eh.typeid.for:
    270
    271 llvm.eh.typeid.for
    272 ------------------
    273
    274 .. code-block:: llvm
    275
    276 i32 @llvm.eh.typeid.for(i8* %type_info)
    277
    278
    279 This intrinsic returns the type info index in the exception table of the current
    280 function. This value can be used to compare against the result of
    281 ``landingpad`` instruction. The single argument is a reference to a type info.
    282
    283 .. _llvm.eh.sjlj.setjmp:
    284
    285 llvm.eh.sjlj.setjmp
    286 -------------------
    287
    288 .. code-block:: llvm
    289
    290 i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
    291
    292 For SJLJ based exception handling, this intrinsic forces register saving for the
    293 current function and stores the address of the following instruction for use as
    294 a destination address by `llvm.eh.sjlj.longjmp`_. The buffer format and the
    295 overall functioning of this intrinsic is compatible with the GCC
    296 ``__builtin_setjmp`` implementation allowing code built with the clang and GCC
    297 to interoperate.
    298
    299 The single parameter is a pointer to a five word buffer in which the calling
    300 context is saved. The front end places the frame pointer in the first word, and
    301 the target implementation of this intrinsic should place the destination address
    302 for a `llvm.eh.sjlj.longjmp`_ in the second word. The following three words are
    303 available for use in a target-specific manner.
    304
    305 .. _llvm.eh.sjlj.longjmp:
    306
    307 llvm.eh.sjlj.longjmp
    308 --------------------
    309
    310 .. code-block:: llvm
    311
    312 void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
    313
    314 For SJLJ based exception handling, the ``llvm.eh.sjlj.longjmp`` intrinsic is
    315 used to implement ``__builtin_longjmp()``. The single parameter is a pointer to
    316 a buffer populated by `llvm.eh.sjlj.setjmp`_. The frame pointer and stack
    317 pointer are restored from the buffer, then control is transferred to the
    318 destination address.
    319
    320 llvm.eh.sjlj.lsda
    321 -----------------
    322
    323 .. code-block:: llvm
    324
    325 i8* @llvm.eh.sjlj.lsda()
    326
    327 For SJLJ based exception handling, the ``llvm.eh.sjlj.lsda`` intrinsic returns
    328 the address of the Language Specific Data Area (LSDA) for the current
    329 function. The SJLJ front-end code stores this address in the exception handling
    330 function context for use by the runtime.
    331
    332 llvm.eh.sjlj.callsite
    333 ---------------------
    334
    335 .. code-block:: llvm
    336
    337 void @llvm.eh.sjlj.callsite(i32 %call_site_num)
    338
    339 For SJLJ based exception handling, the ``llvm.eh.sjlj.callsite`` intrinsic
    340 identifies the callsite value associated with the following ``invoke``
    341 instruction. This is used to ensure that landing pad entries in the LSDA are
    342 generated in matching order.
    343
    344 Asm Table Formats
    345 =================
    346
    347 There are two tables that are used by the exception handling runtime to
    348 determine which actions should be taken when an exception is thrown.
    349
    350 Exception Handling Frame
    351 ------------------------
    352
    353 An exception handling frame ``eh_frame`` is very similar to the unwind frame
    354 used by DWARF debug info. The frame contains all the information necessary to
    355 tear down the current frame and restore the state of the prior frame. There is
    356 an exception handling frame for each function in a compile unit, plus a common
    357 exception handling frame that defines information common to all functions in the
    358 unit.
    359
    360 Exception Tables
    361 ----------------
    362
    363 An exception table contains information about what actions to take when an
    364 exception is thrown in a particular part of a function's code. There is one
    365 exception table per function, except leaf functions and functions that have
    366 calls only to non-throwing functions. They do not need an exception table.
    88 AliasAnalysis
    99 BranchWeightMetadata
    1010 Bugpoint
    11 ExceptionHandling
    1112 LinkTimeOptimization
    1213 SegmentedStacks
    1314 TableGenFundamentals
    4647 This document describes the design and philosophy behind the LLVM
    4748 source-level debugger.
    4849
    49 * `Zero Cost Exception handling in LLVM `_
    50 * :ref:`exception_handling`
    5051
    5152 This document describes the design and implementation of exception handling
    5253 in LLVM.