Exception Handling in LLVM

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 -C/C++.

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

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.

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

+ 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 -specification at Dwarf 3 -Standard. A description for the C++ exception table formats can be found at -Exception Handling -Tables.

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

When an exception is thrown in llvm code, the runtime does a best effort to -find a handler suited to process the circumstance.

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 (ex. -C++) supports exception handling, the exception frame contains a reference to an -exception table describing how to process the exception. If the language (ex. -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.

- -

Since 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 (ex. for C++ __gxx_personality_v0) which -receives the context of the exception, an exception structure containing -the exception object type and value, and a reference the exception table for the -current function. The personality function for the current compile unit is -specified in a common exception frame.

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

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

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.

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.

+ 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 and try/catch statements. In this section + we will describe the implementation of LLVM exception handling in terms of + C++ examples.

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.

+ 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 type info structure.

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.

A call within the scope of a try statement can potential 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 entry points into where a 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 convey information about the landing -pad to the back end.

- -

llvm.eh.exception takes no -arguments and returns the exception structure reference. The backend replaces -this intrinsic with the code that accesses the first argument of a call. The -LLVM C++ front end generates code to save this value in an alloca location for -further use in the landing pad and catch code.

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.

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. The remaining arguments are references to the -type infos for each of the catch statements in the order they should be tested. -The catch all (...) is represented with a null i8*. The result -of the llvm.eh.selector is the index of -the type info in the corresponding exception table. The LLVM C++ front end -generates code to save this value in an alloca location for further use in the -landing pad and catch code.

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 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 a exception structure reference as an argument. This function clears the -exception from the exception space. Note: a rethrow from within the catch may -replace this call with a __cxa_rethrow.

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

- Finallys + 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 (ex., intervening -constructor), there may be several landing pads for a given try.

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.

C++ allows the specification of which exception types that 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.filter instead of llvm.eh.selector. The arguments are the -same, but what gets created in the exception table is different. llvm.eh.filter will return a negative value -if it doesn't find a match. If no match is found then a call to -__cxa_call_unexpected should be made, otherwise -_Unwind_Resume. Each of these functions require a reference to the -exception structure.

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.

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

+ provide exception handling information at various points in generated + code.

   i8* %llvm.eh.exception( )

This intrinsic indicates that the exception structure is available at this -point in the code. The backend will replace this intrinsic with code to fetch -the first argument of a call. The effect is that the intrinsic result is the -exception structure reference.

This intrinsic returns a pointer to the exception structure.

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

This intrinsic indicates that the exception selector is available at this -point in the code. The backend will replace this intrinsic with code to fetch -the second argument of a call. The effect is that the intrinsic result is the -exception selector.

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

+ 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.filter + llvm.eh.typeid.for

-  i32 %llvm.eh.filter(i8*, i8*, i8*, ...)
+  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.filter 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 function. The remaining arguments are references to the type infos -for each type that can be thrown by the current function.

+ 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.typeid.for + llvm.eh.sjlj.lsda

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

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.

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.

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

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

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.

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

@@ -410,9 +546,9 @@ all functions in the unit.

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.

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

@@ -427,16 +563,7 @@ only calls to non-throwing functions will not need an exception table.

Need to create landing pads for code in between explicit landing pads. -The landing pads will have a zero action and a NULL landing pad address and are -used to inform the runtime that the exception should be rethrown.

Actions for a given function should be folded to save space.
Filters for inlined functions need to be handled more extensively. -Currently it's hardwired for one filter per function.

Testing/Testing/Testing.

Testing/Testing/Testing.

@@ -447,9 +574,9 @@ Currently it's hardwired for one filter per function.

+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS">

+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"> Chris Lattner
LLVM Compiler Infrastructure