llvm.org GIT mirror llvm / 2a6b073
Some minor (and more involved) cleanups. No real context changes. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@140561 91177308-0d34-0410-b5e6-96231b3b80d8 Bill Wendling 8 years ago
1 changed file(s) with 126 addition(s) and 133 deletion(s). Raw diff Collapse all Expand all
6565 handling information takes, which is useful for those interested in creating
6666 front-ends or dealing directly with the information. Further, this document
6767 provides specific examples of what exception handling information is used for
68 in C/C++.

68 in C and C++.

6969
7070
7171

145145
146146

The runtime first attempts to find an exception frame corresponding to

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

157157
158158

Because different programming languages have different behaviors when

159159 handling exceptions, the exception handling ABI provides a mechanism for
160 supplying personalities. An exception handling personality is defined
160 supplying personalities. An exception handling personality is defined
161161 by way of a personality function (e.g. __gxx_personality_v0
162162 in C++), which receives the context of the exception, an exception
163163 structure containing the exception object type and value, and a reference
165165 for the current compile unit is specified in a common exception
166166 frame.

167167
168

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

168

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

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

175175
176

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

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

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

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

181182
182183
183184
190191
191192
192193
193

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

194

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

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

203204
204205
205206

Languages that support exception handling typically provide a throw

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

209
208210
209211
  • A request is made to allocate exception space for an exception structure.
  • 210212 This structure needs to survive beyond the current activation. This
    211213 structure will contain the type and value of the object being thrown.
    214
    212215
  • A call is made to the runtime to raise the exception, passing the
  • 213216 exception structure as an argument.
    214217
    215218
    216

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

    219

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

    217220 __cxa_allocate_exception runtime function. The exception raising is
    218221 handled by __cxa_throw. The type of the exception is represented
    219222 using a C++ RTTI structure.

    228231
    229232
    230233

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

    231 exception. In those circumstances, the LLVM C++ front-end replaces the call
    232 with an invoke instruction. Unlike a call, the invoke has
    233 two potential continuation points: where to continue when the call succeeds
    234 as per normal; and where to continue if the call raises an exception, either
    235 by a throw or the unwinding of a throw.

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

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

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

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

    243251
    244252

    The LLVM landingpad

    245253 instruction is used to convey information about the landing pad to the
    246254 back end. For C++, the landingpad instruction returns a pointer and
    247 integer pair corresponding to the pointer to the exception structure and the
    248 "selector value" respectively.>
    255 integer pair corresponding to the pointer to the exception structure>
    256 and the selector value respectively.

    249257
    250258

    The landingpad instruction takes a reference to the personality

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

    261269
    262270

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

    263271 code for the first catch. The catch then checks the value of the type info
    264272 selector against the index of type info for that catch. Since the type info
    265 index is not known until all the type info have been gathered in the backend,
    266 the catch code will call the
    273 index is not known until all the type infos have been gathered in the
    274 backend, the catch code must call the
    267275 llvm.eh.typeid.for intrinsic to
    268276 determine the index for a given type info. If the catch fails to match the
    269 selector then control is passed on to the next catch. Note: Since the landing
    270 pad will not be used if there is no match in the list of type info on the
    271 call to the landingpad
    272 instruction, then neither the last catch nor catch all need to
    273 perform the check against the selector.

    274
    275

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

    276 to __cxa_begin_catch and __cxa_end_catch.

    277 selector then control is passed on to the next catch.

    278
    279

    Note: Since the landing pad will not be used if there is no match in

    280 the list of type info on the call to the landingpad instruction,
    281 then neither the last catch nor catch all need to perform the check
    282 against the selector.

    283
    284

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

    285 __cxa_begin_catch and __cxa_end_catch.

    277286
    278287
    279
  • __cxa_begin_catch takes a exception structure reference as an
  • 288
  • __cxa_begin_catch takes an exception structure reference as an
  • 280289 argument and returns the value of the exception object.
    281290
    282291
  • __cxa_end_catch takes no arguments. This function:

  • 283292
    284293
  • Locates the most recently caught exception and decrements its handler
  • 285294 count,
    286
  • Removes the exception from the "caught" stack if the handler count
  • 287 goes to zero, and
    288
  • Destroys the exception if the handler count goes to zero, and the
  • 295
  • Removes the exception from the caught stack if the handler
  • 296 count goes to zero, and
    297
  • Destroys the exception if the handler count goes to zero and the
  • 289298 exception was not re-thrown by throw.
    290299
    291

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

    300

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

    292301 a __cxa_rethrow.

    293302
    294303
    302311
    303312
    304313

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

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

    312321
    313

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

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

    318
    319

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

    320 by the current function, resume unwinding by calling the
    322

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

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

    327
    328

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

    329 current function, resume unwinding by calling the
    321330 resume instruction, passing in
    322 the results of the landingpad instruction for the original landing
    331 the result of the landingpad instruction for the original landing
    323332 pad.

    324333
    325334
    331340
    332341
    333342
    334

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

    335 function. To represent this a top level landing pad may exist to filter out
    336 invalid types. To express this in LLVM code the
    343

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

    344 function. To represent this, a top level landing pad may exist to filter out
    345 invalid types. To express this in LLVM code the
    337346 landingpad instruction will
    338347 have a filter clause. The clause consists of an array of type infos.
    339348 landingpad will return a negative value if the exception does not
    357366
    358367
    359368

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

    360 that call frame's language-specific personality function. Not all
    361 personalities functions guarantee that they will stop to perform
    362 cleanups. For example, the GNU C++ personality doesn't do so unless the
    363 exception is actually caught somewhere further up the stack. When using this
    364 personality to implement EH for a language that guarantees that cleanups will
    365 always be run, be sure to indicate a catch-all in the
    369 that call frame's language-specific personality function. Not all personality
    370 functions guarantee that they will stop to perform cleanups. For example, the
    371 GNU C++ personality function doesn't do so unless the exception is actually
    372 caught somewhere further up the stack. When using this personality to
    373 implement EH for a language that guarantees that cleanups will always be run
    374 (e.g. Ada), be sure to indicate a catch-all in the
    366375 landingpad instruction
    367376 rather than just cleanups.

    368377
    369378

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

    370 handle selector results that they did not originally advertise. Suppose that
    379 handle selector results that they did not originally advertise. Suppose that
    371380 a function catches exceptions of type A, and it's inlined into a
    372 function that catches exceptions of type B. The inliner will update
    381 function that catches exceptions of type B. The inliner will update
    373382 the landingpad instruction for the inlined landing pad to include
    374 the fact that B is caught. If that landing pad assumes that it will
    375 only be entered to catch an A, it's in for a rude surprise.
    383 the fact that B is also caught. If that landing pad assumes that it
    384 will only be entered to catch an A, it's in for a rude awakening.
    376385 Consequently, landing pads must test for the selector results they understand
    377386 and then resume exception propagation with the
    378387 resume instruction if none of
    392401

    In addition to the

    393402 landingpad and
    394403 resume instructions, LLVM uses
    395 several intrinsic functions (name prefixed with "llvm.eh") to
    404 several intrinsic functions (name prefixed with llvm.eh) to
    396405 provide exception handling information at various points in generated
    397406 code.

    398407
    404413
    405414
    406415
    
                      
                    
    407 i32 %llvm.eh.typeid.for(i8*)
    416 i32 @llvm.eh.typeid.for(i8* %type_info)
    408417
    409418
    410419

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

    422431
    423432
    424433
    
                      
                    
    425 i32 %llvm.eh.sjlj.setjmp(i8*)
    434 i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
    426435
    427436
    428

    The SJLJ exception handling uses this intrinsic to force register saving for

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

    437

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

    438 the current function and stores the address of the following instruction for
    439 use as a destination address
    440 by llvm.eh.sjlj.longjmp. The
    441 buffer format and the overall functioning of this intrinsic is compatible
    442 with the GCC __builtin_setjmp implementation allowing code built
    443 with the clang and GCC to interoperate.

    435444
    436445

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

    437446 context is saved. The front end places the frame pointer in the first word,
    451460
    452461
    453462
    
                      
                    
    454 void %llvm.eh.sjlj.setjmp(i8*)
    463 void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
    455464
    456465
    457

    The llvm.eh.sjlj.longjmp

    458 intrinsic is used to implement __builtin_longjmp() for SJLJ
    459 style exception handling. The single parameter is a pointer to a
    460 buffer populated by
    461 llvm.eh.sjlj.setjmp. The frame pointer and stack pointer
    462 are restored from the buffer, then control is transferred to the
    463 destination address.>
    466

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

    467 intrinsic is used to implement __builtin_longjmp(). The single
    468 parameter is a pointer to a buffer populated
    469 by llvm.eh.sjlj.setjmp. The frame
    470 pointer and stack pointer are restored from the buffer, then control is
    471 transferred to the destination address.

    464472
    465473
    466474
    471479
    472480
    473481
    
                      
                    
    474 i8* %llvm.eh.sjlj.lsda()
    482 i8* @llvm.eh.sjlj.lsda()
    475483
    476484
    477

    Used for SJLJ based exception handling, the

    478 llvm.eh.sjlj.lsda intrinsic returns the address of the Language
    479 Specific Data Area (LSDA) for the current function. The SJLJ front-end code
    480 stores this address in the exception handling function context for use by the
    481 runtime.

    485

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

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

    482489
    483490
    484491
    490497
    491498
    492499
    
                      
                    
    493 void %llvm.eh.sjlj.callsite(i32)
    500 void @llvm.eh.sjlj.callsite(i32 %call_site_num)
    494501
    495502
    496

    For SJLJ based exception handling, the

    497 llvm.eh.sjlj.callsite intrinsic identifies the callsite value
    498 associated with the following invoke instruction. This is used to ensure
    499 that landing pad entries in the LSDA are generated in the matching order.>
    503

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

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

    500507
    501508
    502509
    508515
    509516
    510517
    
                      
                    
    511 void %llvm.eh.sjlj.dispatchsetup(i32)
    518 void @llvm.eh.sjlj.dispatchsetup(i32 %dispatch_value)
    512519
    513520
    514

    For SJLJ based exception handling, the

    515 llvm.eh.sjlj.dispatchsetup intrinsic is used by targets to do
    516 any unwind-edge setup they need. By default, no action is taken. >
    521

    For SJLJ based exception handling, the llvm.eh.sjlj.dispatchsetup>

    522 intrinsic is used by targets to do any unwind edge setup they need. By
    523 default, no action is taken.

    517524
    518525
    519526
    527534
    528535
    529536

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

    530 determine which actions should take place when an exception is thrown.

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

    531538
    532539
    533540

    537544
    538545
    539546

    An exception handling frame eh_frame is very similar to the unwind

    540 frame used by dwarf debug info. The frame contains all the information
    547 frame used by DWARF debug info. The frame contains all the information
    541548 necessary to tear down the current frame and restore the state of the prior
    542 frame. There is an exception handling frame for each function in a compile
    549 frame. There is an exception handling frame for each function in a compile
    543550 unit, plus a common exception handling frame that defines information common
    544551 to all functions in the unit.

    545552
    546 <p>Todo - Table details here.>
    553 <!-- Todo - Table details here. -->
    547554
    548555
    549556
    555562
    556563
    557564

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

    558 exception is thrown in a particular part of a function's code. There is one
    559 exception table per function except leaf routines and functions that have
    560 only calls to non-throwing functions will not need an exception table.

    561
    562

    Todo - Table details here.

    563
    564
    565
    566
    567
    568
    569

    570 ToDo
    571
    572
    573
    574
    575
    576
    577
  • Testing/Testing/Testing.
  • 578
    579
    565 exception is thrown in a particular part of a function's code. There is one
    566 exception table per function, except leaf functions and functions that have
    567 calls only to non-throwing functions. They do not need an exception
    568 table.

    569
    570
    571
    572
    580573
    581574
    582575