airs-notes/gcc_except_table.md

.gcc_except_table

Throwing an exception in C++ requires more than unwinding the stack. As the program unwinds, local variable destructors must be executed. Catch clauses must be examined to see if they should catch the exception. Exception specifications must be checked to see if the exception should be redirected to the unexpected handler. Similar issues arise in Go, Java, and even C when using gcc’s cleanup function attribute.

As I described earlier, each CIE in the unwind data may contain a pointer to a personality function, and each FDE may contain a pointer to the LSDA, the Language Specific Data Area. Each language has its own personality function. The LSDA is only used by the personality function, so it could in principle differ for each language. However, at least for gcc, every language uses the same format, since the LSDA is generated by the language-independent middle-end.

The personality function takes five arguments:

1. A int version number, currently 1.
2. A bitmask of actions.
3. An exception class, a 64-bit unsigned integer which is specific to a language.
4. A pointer to information about the specific exception being thrown.
5. Unwinder state information.

The exception class permits code written in one language to work correctly when an exception is thrown by code written in a different language. The value for g++ is “GNUCC++\0” (or “GNUCC++\1” for a dependent exception, which is used when rethrowing an exception). The value for Go is “GNUCGO\0\0”. The exception specific information can only be examined if the exception class is recognized.

Unwinding the stack for an exception is done in two phases. In the first phase, the unwinder walks up the stack passing the action _UA_SEARCH_PHASE (which has the value 1) to each personality function that it finds. The personality function should examine the LSDA to see if there is a handler for the exception being thrown. It should return _URC_HANDLER_FOUND (6) if there is or _URC_CONTINUE_UNWIND (8) if there isn’t. The search phase will continue until a handler is found or until the top of the stack is reached. The unwinder will not actually change anything while walking. If the top of the stack is reached the unwinder will simply return, and the calling code will take the appropriate action, which for C++ is to call std::terminate. Because of the two phase unwinding approach, if std::terminate dumps core, a backtrace will show the code which threw the exception.

If a handler is found, the second phase begins. The unwinder walks up the stack passing the action _UA_CLEANUP_PHASE (2) to each personality function. The unwinder will also set _UA_FORCE_UNWIND (8) in the actions bitmask if the personality function may not catch the exception, because the unwinding is happening due to some event like thread cancellation. The unwinder will walk up the stack until it finds the handler—the stack frame for which the personality function returned _URC_HANDLER_FOUND. When it calls that function, the unwinder will pass _UA_HANDLER_FRAME (4) in the actions bitmask. This time, the unwinder will changes things as it goes, removing stack frames.

In order to run destructors, the personality function will call _Unwind_SetIP on the context parameter to set the program counter to point to the cleanup routine, and then return _URC_INSTALL_CONTEXT (7) to tell the unwinder to branch to the current context. The address which starts the cleanup is known as a landing pad. The cleanup should do whatever it needs to do, and then call _Unwind_Resume. The exception information needs to be passed to _Unwind_Resume. The personality routine arranges to pass the exception information to the cleanup by calling _Unwind_SetGR passing __builtin_eh_return_data_regno(0) and the exception information passed to the personality routine. Each target which supports this approach has to dedicate two registers to holding exception information. This is the first one.

The personality function which finds the handler works pretty much the same way. It may also use _Unwind_SetGR to set a value in __builtin_eh_return_data_regno(1) to indicate which exception was found. The exception handler may rethrow the exception via _Unwind_RaiseException or it may simply continue a normal execution path.

At this point we’ve seen everything except how the personality function decides whether it needs to run a cleanup or catch an exception. The personality function makes this decision based on the LSDA. As mentioned above, while the LSDA could be language dependent, in practice it is not. There is a different personality function for each language, but they all do more or less the same thing, omitting aspects which are not relevant for the language (e.g., there is a personality function for C, but it only runs cleanups and does not bother to look for exception handlers).

The LSDA is found in the section .gcc_except_table (the personality function is just a function and lives in the .text section as usual). The personality function gets a pointer to it by calling _Unwind_GetLanguageSpecificData. The LSDA starts with the following fields:

1. A 1 byte encoding of the following field (a DW_EH_PE_xxx value).
2. If the encoding is not DW_EH_PE_omit, the landing pad base. This is the base from which landing pad offsets are computed. If this is omitted, the base comes from calling _Unwind_GetRegionStart, which returns the beginning of the code described by the current FDE. In practice this field is normally omitted.
3. A 1 byte encoding of the entries in the type table (a DW_EH_PE_xxx value).
4. If the encoding is not DW_EH_PE_omit, the types table pointer. This is an unsigned LEB128 value, and is the byte offset from this field to the start of the types table used for exception matching.
5. A 1 byte encoding of the fields in the call-site table (a DW_EH_PE_xxx value).
6. An unsigned LEB128 value holding the length in bytes of the call-site table.

This header is immediately followed by the call-site table. Each entry in the call-site table has four fields. The number of bytes in the header gives the total length. Each entry in the call-site table describes a particular sequence of instructions within the function that the FDE desribes.

1. The start of the instructions for the current call site, a byte offset from the landing pad base. This is encoded using the encoding from the header.
2. The length of the instructions for the current call site, in bytes. This is encoded using the encoding from the header.
3. A pointer to the landing pad for this sequence of instructions, or 0 if there isn’t one. This is a byte offset from the landing pad base. This is encoded using the encoding from the header.
4. The action to take, an unsigned LEB128. This is 1 plus a byte offset into the action table. The value zero means that there is no action.

The call-site table is sorted by the start address field. If the personality function finds that there is no entry for the current PC in the call-site table, then there is no exception information. This should not happen in normal operation, and in C++ will lead to a call to std::terminate. If there is an entry in the call-site table, but the landing pad is zero, then there is nothing to do: there are no destructors to run or exceptions to catch. This is a normal case, and the unwinder will simply continue. If the action record is zero, then there are destructors to run but no exceptions to catch. The personality function will arrange to run the destructors as described above, and unwinding will continue.

Otherwise, we have an offset into the action table. Each entry in the action table is a pair of signed LEB128 values. The first number is a type filter. The second number is a byte offset to the next entry in the action table. A byte offset of 0 ends the current set of actions.

A type filter of zero indicates a cleanup, which is the same as an action record of zero in the call-site table. This means that there is a cleanup to be called even if none of the types match.

A positive type filter is an index into the types table. This is a negative index: the value 1 means the entry preceding the types table base, 2 means the entry before that, etc. The size of entries in the types table comes from the encoding in the header, as does the base of the types table. Each entry in the types table is a pointer to a type information structure. If this type information structure matches the type of the exception, then we have found a handler for this exception. The type filter value is a switch value will be passed to the handler in exception register 1. The actual comparison of the type information, and determining the type information from the exception pointer, really is language dependent. In C++ this is a pointer to a std::type_info structure. A NULL pointer in the types table is a catch-all handler.

A negative type filter is a byte offset into the types table of a NULL terminated list of pointers to type information structures. If the type of the current exception does not match any of the entries in the list, then there is an exception specification error. This is treated as an exception handler with a negative switch value.

I think that covers everything about how gcc unwinds the stack and throws exceptions.