Exception Handling in LLVM

Date: Thu, 6 May 2010 23:45:43 +0000 Subject: Overhauled llvm/clang docs builds. Closes PR6613. NOTE: 2nd part changeset for cfe trunk to follow. *** PRE-PATCH ISSUES ADDRESSED - clang api docs fail build from objdir - clang/llvm api docs collide in install PREFIX/ - clang/llvm main docs collide in install - clang/llvm main docs have full of hard coded destination assumptions and make use of absolute root in static html files; namely CommandGuide tools hard codes a website destination for cross references and some html cross references assume website root paths *** IMPROVEMENTS - bumped Doxygen from 1.4.x -> 1.6.3 - splits llvm/clang docs into 'main' and 'api' (doxygen) build trees - provide consistent, reliable doc builds for both main+api docs - support buid vs. install vs. website intentions - support objdir builds - document targets with 'make help' - correct clean and uninstall operations - use recursive dir delete only where absolutely necessary - added call function fn.RMRF which safeguards against botched 'rm -rf'; if any target (or any variable is evaluated) which attempts to remove any dirs which match a hard-coded 'safelist', a verbose error will be printed and make will error-stop. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103213 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ExceptionHandling.html | 606 -------------------------------------------- 1 file changed, 606 deletions(-) delete mode 100644 docs/ExceptionHandling.html (limited to 'docs/ExceptionHandling.html') diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html deleted file mode 100644 index 9c7c615052..0000000000 --- a/docs/ExceptionHandling.html +++ /dev/null @@ -1,606 +0,0 @@ - - - - Exception Handling in LLVM - - - - - - - -

- - - - - - -

Written by Jim Laskey

- - - -

Introduction

- - -

- -

This document is the central repository for all information pertaining to - exception handling in LLVM. It describes the format that LLVM exception - handling information takes, which is useful for those interested in creating - front-ends or dealing directly with the information. Further, this document - provides specific examples of what exception handling information is used for - in C/C++.

- -

- - -

- Itanium ABI Zero-cost Exception Handling -

- -

Exception handling for most programming languages is designed to recover from - conditions that rarely occur during general use of an application. To that - end, exception handling should not interfere with the main flow of an - application's algorithm by performing checkpointing tasks, such as saving the - current pc or register state.

- -

The Itanium ABI Exception Handling Specification defines a methodology for - providing outlying data in the form of exception tables without inlining - speculative exception handling code in the flow of an application's main - algorithm. Thus, the specification is said to add "zero-cost" to the normal - execution of an application.

- -

A more complete description of the Itanium ABI exception handling runtime - support of can be found at - Itanium C++ ABI: - Exception Handling. A description of the exception frame format can be - found at - Exception - Frames, with details of the DWARF 3 specification at - DWARF 3 Standard. - A description for the C++ exception table formats can be found at - Exception Handling - Tables.

- -

- - -

- Setjmp/Longjmp Exception Handling -

- -

Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics - llvm.eh.sjlj.setjmp and - llvm.eh.sjlj.longjmp to - handle control flow for exception handling.

- -

For each function which does exception processing, be it try/catch blocks - or cleanups, that function registers itself on a global frame list. When - exceptions are being unwound, the runtime uses this list to identify which - functions need processing.

- -

Landing pad selection is encoded in the call site entry of the function - context. The runtime returns to the function via - llvm.eh.sjlj.longjmp, where - a switch table transfers control to the appropriate landing pad based on - the index stored in the function context.

- -

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

- - -

- Overview -

- -

When an exception is thrown in LLVM code, the runtime does its best to find a - handler suited to processing the circumstance.

- -

The runtime first attempts to find an exception frame corresponding to - the function where the exception was thrown. If the programming language - (e.g. C++) supports exception handling, the exception frame contains a - reference to an exception table describing how to process the exception. If - the language (e.g. C) does not support exception handling, or if the - exception needs to be forwarded to a prior activation, the exception frame - contains information about how to unwind the current activation and restore - the state of the prior activation. This process is repeated until the - exception is handled. If the exception is not handled and no activations - remain, then the application is terminated with an appropriate error - message.

- -

Because different programming languages have different behaviors when - handling exceptions, the exception handling ABI provides a mechanism for - supplying personalities. An exception handling personality is defined - by way of a personality function (e.g. __gxx_personality_v0 - in C++), which receives the context of the exception, an exception - structure containing the exception object type and value, and a reference - to the exception table for the current function. The personality function - for the current compile unit is specified in a common exception - frame.

- -

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

- -

A landing pad corresponds to the code found in the catch portion of - a try/catch sequence. When execution resumes at a landing - pad, it receives the exception structure and a selector corresponding to - the type of exception thrown. The selector is then used to determine - which catch should actually process the exception.

- -

- - -

- LLVM Code Generation -

- -

At the time of this writing, only C++ exception handling support is available - in LLVM. So the remainder of this document will be somewhat C++-centric.

- -

From the C++ developers perspective, exceptions are defined in terms of the - throw and try/catch statements. In this section - we will describe the implementation of LLVM exception handling in terms of - C++ examples.

- -

- - -

- Throw -

- -

Languages that support exception handling typically provide a throw - operation to initiate the exception process. Internally, a throw operation - breaks down into two steps. First, a request is made to allocate exception - space for an exception structure. This structure needs to survive beyond the - current activation. This structure will contain the type and value of the - object being thrown. Second, a call is made to the runtime to raise the - exception, passing the exception structure as an argument.

- -

In C++, the allocation of the exception structure is done by - the __cxa_allocate_exception runtime function. The exception - raising is handled by __cxa_throw. The type of the exception is - represented using a C++ RTTI structure.

- -

- - -

- Try/Catch -

- -

A call within the scope of a try statement can potentially raise an - exception. In those circumstances, the LLVM C++ front-end replaces the call - with an invoke instruction. Unlike a call, the invoke has - two potential continuation points: where to continue when the call succeeds - as per normal; and where to continue if the call raises an exception, either - by a throw or the unwinding of a throw.

- -

The term used to define a the place where an invoke continues after - an exception is called a landing pad. LLVM landing pads are - conceptually alternative function entry points where an exception structure - reference and a type info index are passed in as arguments. The landing pad - saves the exception structure reference and then proceeds to select the catch - block that corresponds to the type info of the exception object.

- -

Two LLVM intrinsic functions are used to convey information about the landing - pad to the back end.

- -

llvm.eh.exception takes no - arguments and returns a pointer to the exception structure. This only - returns a sensible value if called after an invoke has branched - to a landing pad. Due to code generation limitations, it must currently - be called in the landing pad itself.
llvm.eh.selector takes a minimum - of three arguments. The first argument is the reference to the exception - structure. The second argument is a reference to the personality function - to be used for this try/catch sequence. Each of the - remaining arguments is either a reference to the type info for - a catch statement, a filter - expression, or the number zero (0) representing - a cleanup. The exception is tested against the - arguments sequentially from first to last. The result of - the llvm.eh.selector is a - positive number if the exception matched a type info, a negative number if - it matched a filter, and zero if it matched a cleanup. If nothing is - matched, the behaviour of the program - is undefined. This only returns a sensible - value if called after an invoke has branched to a landing pad. - Due to codegen limitations, it must currently be called in the landing pad - itself. If a type info matched, then the selector value is the index of - the type info in the exception table, which can be obtained using the - llvm.eh.typeid.for - intrinsic.

- -

Once the landing pad has the type info selector, the code branches to the - code for the first catch. The catch then checks the value of the type info - selector against the index of type info for that catch. Since the type info - index is not known until all the type info have been gathered in the backend, - the catch code will call the - llvm.eh.typeid.for intrinsic - to determine the index for a given type info. If the catch fails to match - the selector then control is passed on to the next catch. Note: Since the - landing pad will not be used if there is no match in the list of type info on - the call to llvm.eh.selector, then - neither the last catch nor catch all need to perform the check - against the selector.

- -

Finally, the entry and exit of catch code is bracketed with calls - to __cxa_begin_catch and __cxa_end_catch.

- -

__cxa_begin_catch takes a exception structure reference as an - argument and returns the value of the exception object.
__cxa_end_catch takes no arguments. This function:

-
1. Locates the most recently caught exception and decrements its handler - count,
2. Removes the exception from the "caught" stack if the handler count - goes to zero, and
3. Destroys the exception if the handler count goes to zero, and the - exception was not re-thrown by throw.
-
Note: a rethrow from within the catch may replace this call with - a __cxa_rethrow.

- -

- - -

- Cleanups -

- -

To handle destructors and cleanups in try code, control may not run - directly from a landing pad to the first catch. Control may actually flow - from the landing pad to clean up code and then to the first catch. Since the - required clean up for each invoke in a try may be different - (e.g. intervening constructor), there may be several landing pads for a given - try. If cleanups need to be run, an i32 0 should be passed as the - last llvm.eh.selector argument. - However, when using DWARF exception handling with C++, a i8* null - must be passed instead.

- -

- - -

- Throw Filters -

- -

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

- -

- - -

- Restrictions -

- -

The semantics of the invoke instruction require that any exception that - unwinds through an invoke call should result in a branch to the invoke's - unwind label. However such a branch will only happen if the - llvm.eh.selector matches. Thus in - order to ensure correct operation, the front-end must only generate - llvm.eh.selector calls that are - guaranteed to always match whatever exception unwinds through the invoke. - For most languages it is enough to pass zero, indicating the presence of - a cleanup, as the - last llvm.eh.selector argument. - However for C++ this is not sufficient, because the C++ personality function - will terminate the program if it detects that unwinding the exception only - results in matches with cleanups. For C++ a null i8* should be - passed as the last llvm.eh.selector - argument instead. This is interpreted as a catch-all by the C++ personality - function, and will always match.

- -

- - -

- Exception Handling Intrinsics -

- -

LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to - provide exception handling information at various points in generated - code.

- -

- - -

- llvm.eh.exception -

- -

-  i8* %llvm.eh.exception( )
-

- -

This intrinsic returns a pointer to the exception structure.

- -

- - -

- llvm.eh.selector -

- -

-  i32 %llvm.eh.selector(i8*, i8*, i8*, ...)
-

- -

This intrinsic is used to compare the exception with the given type infos, - filters and cleanups.

- -

llvm.eh.selector takes a minimum of - three arguments. The first argument is the reference to the exception - structure. The second argument is a reference to the personality function to - be used for this try catch sequence. Each of the remaining arguments is - either a reference to the type info for a catch statement, - a filter expression, or the number zero - representing a cleanup. The exception is tested - against the arguments sequentially from first to last. The result of - the llvm.eh.selector is a positive - number if the exception matched a type info, a negative number if it matched - a filter, and zero if it matched a cleanup. If nothing is matched, the - behaviour of the program is undefined. If a type - info matched then the selector value is the index of the type info in the - exception table, which can be obtained using the - llvm.eh.typeid.for intrinsic.

- -

- - -

- llvm.eh.typeid.for -

- -

-  i32 %llvm.eh.typeid.for(i8*)
-

- -

This intrinsic returns the type info index in the exception table of the - current function. This value can be used to compare against the result - of llvm.eh.selector. The single - argument is a reference to a type info.

- -

- - -

- llvm.eh.sjlj.setjmp -

- -

-  i32 %llvm.eh.sjlj.setjmp(i8*)
-

- -

The SJLJ exception handling uses this intrinsic to force register saving for - the current function and to store the address of the following instruction - for use as a destination address by - llvm.eh.sjlj.longjmp. The buffer format and the overall - functioning of this intrinsic is compatible with the GCC - __builtin_setjmp implementation, allowing code built with the - two compilers to interoperate.

- -

The single parameter is a pointer to a five word buffer in which the calling - context is saved. The front end places the frame pointer in the first word, - and the target implementation of this intrinsic should place the destination - address for a - llvm.eh.sjlj.longjmp in the - second word. The following three words are available for use in a - target-specific manner.

- -

- - -

- llvm.eh.sjlj.lsda -

- -

-  i8* %llvm.eh.sjlj.lsda( )
-

- -

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

- -

- - -

- llvm.eh.sjlj.callsite -

- -

-  void %llvm.eh.sjlj.callsite(i32)
-

- -

For SJLJ based exception handling, the - llvm.eh.sjlj.callsite intrinsic identifies the callsite value - associated with the following invoke instruction. This is used to ensure - that landing pad entries in the LSDA are generated in the matching order.

- -

- - -

- Asm Table Formats -

- -

There are two tables that are used by the exception handling runtime to - determine which actions should take place when an exception is thrown.

- -

- - -

- Exception Handling Frame -

- -

An exception handling frame eh_frame is very similar to the unwind - frame used by dwarf debug info. The frame contains all the information - necessary to tear down the current frame and restore the state of the prior - frame. There is an exception handling frame for each function in a compile - unit, plus a common exception handling frame that defines information common - to all functions in the unit.

- -

Todo - Table details here.

- -

- - -

- Exception Tables -

- -

An exception table contains information about what actions to take when an - exception is thrown in a particular part of a function's code. There is one - exception table per function except leaf routines and functions that have - only calls to non-throwing functions will not need an exception table.

- -

Todo - Table details here.

- -

- - -

- ToDo -

- -

Testing/Testing/Testing.

- -

- - - -

- - Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date$ -

- - - -- cgit v1.2.3