Nynaeve

This is a series dealing with how to use the new x64 exception handling support from a programmatic perspective (that is, how to write programs that take advantage of the new support, instead of the perspective of how to understand it while reverse engineering or disassembling something. Those topics have been covered in the past on this site already.)

To get started with programming against the new x64 EH support, you’ll need to have the structure and prototype definitions for the standard x64 EH related functions and structures. One’s first instinct here is to go to MSDN. Be warned, that if you are dealing with the low-level SEH routines (such as RtlUnwindEx), the documentation on MSDN is still missing / wrong for x64. For the most part, excepting RtlVirtualUnwind (which is actually correctly documented now), the exception handler support is only properly documented for IA64 (so don’t be surprised if things don’t work out how you would hope when calling RtlUnwindEx with the MSDN prototype).

For a recent project, I had to do some in-depth work with the inner workings of exception handling support on x64. So, if you’ve been ever having to deal with the low-level EH internals on x64 and have been frustrated by documentation on MSDN that is either incomplete or just plain wrong, here’s some of the things that I have run into along the way as far as things that are either missing or incorrect on MSDN while relating to x64 EH support:

1. When processing an UNWIND_INFO structure, if the UNW_FLAG_CHAININFO flag is set, then there is an additional undocumented possibility for how unwind information can be chained. Specifically, if the low bit is set in the UnwindInfoAddress of the IMAGE_RUNTIME_FUNCTION_ENTRY structure referring to by the parent UNWIND_INFO structure, UnwindInfoAddress is actually the RVA of another IMAGE_RUNTIME_FUNCTION_ENTRY structure after zeroing the first bit (instead of the RVA of an UNWIND_INFO structure). This is used to help more efficiently chain exception data across a binary with minimal waste of space (credits go to skape for telling me about this).
2. The prototype on MSDN for RtlUnwindEx is only for IA64 and does not apply to x64. The correct prototype is something more on the lines of this:

   VOID
   NTAPI
   RtlUnwindEx(
      __in_opt ULONG64               TargetFrame,
      __in_opt ULONG64               TargetIp,
      __in_opt PEXCEPTION_RECORD     ExceptionRecord,
      __in     PVOID                 ReturnValue,
      __out    PCONTEXT              OriginalContext,
      __in_opt PUNWIND_HISTORY_TABLE HistoryTable
      );

3. MSDN’s definition of DISPATCHER_CONTEXT (a structure that is passed to the language specific handler) is incomplete. There are some additional fields beyond HandlerData, which is the last field documented in MSDN. You can see this if you disassemble _C_specific_handler, which uses the undocumented ScopeIndex field. Additional credits go to Alex Ionescu for information on a couple of the undocumented DISPATCHER_CONTEXT fields. Here’s the correct definition of this structure for x64:

   typedef struct _DISPATCHER_CONTEXT {
       ULONG64               ControlPc;
       ULONG64               ImageBase;
       PRUNTIME_FUNCTION     FunctionEntry;
       ULONG64               EstablisherFrame;
       ULONG64               TargetIp;
       PCONTEXT              ContextRecord;
       PEXCEPTION_ROUTINE    LanguageHandler;
       PVOID                 HandlerData;
       PUNWIND_HISTORY_TABLE HistoryTable;
       ULONG                 ScopeIndex;
       ULONG                 Fill0;
   } DISPATCHER_CONTEXT, *PDISPATCHER_CONTEXT;

4. Not all of the flags passed to an exception handler (primarily relating to unwinding) are properly documented on MSDN. These additional flags are included in winnt.h, however, and are actually the same for both x86 and x64. Here’s a listing of the missing flags that apply to the ExceptionFlags member of the EXCEPTION_RECORD structure (only the EXCEPTION_NONCONTINUABLE flag value is documented on MSDN):

   #define EXCEPTION_NONCONTINUABLE   0x0001
   #define EXCEPTION_UNWINDING        0x0002
   #define EXCEPTION_EXIT_UNWIND      0x0004
   #define EXCEPTION_STACK_INVALID    0x0008
   #define EXCEPTION_NESTED_CALL      0x0010
   #define EXCEPTION_TARGET_UNWIND    0x0020
   #define EXCEPTION_COLLIDED_UNWIND  0x0040
   #define EXCEPTION_UNWIND           0x0066

   In particular, EXCEPTION_UNWIND is a bitmask of other flags that indicates all possible flags that are used to signify an unwind operation. This is probably the most interesting bitmask/flag to you, as you’ll need it if you are distinguishing from an exception or an unwind operation from the perspective of an exception handler.

5. The definition for the C scope-table information emitted by CL for __try/__except/__finally and implicit exception handlers is not documented. Here’s the definition of the scope table used for C exception handling support:

   typedef struct _SCOPE_TABLE {
   	ULONG Count;
   	struct
   	{
   		 ULONG BeginAddress;
   		 ULONG EndAddress;
   		 ULONG HandlerAddress;
   		 ULONG JumpTarget;
   	} ScopeRecord[ 1 ];
    } SCOPE_TABLE, *PSCOPE_TABLE;
   

   This structure was briefly documented in a beta release of the WDK, although it has since disappeared from the RTM build. The ScopeRecord field describes a variable-sized array whose length is given by the Count field.
   You’ll need this structure definition if you are interacting with _C_specific_handler, or implementing assembler routines that are intended to use _C_specific_handler as their language specific handler.
   All of the above addresses are RVAs. BeginAddress and EndAddress are the RVAs for which the current scope record is effective for. HandlerAddress is the RVA of a C-specific exception handler (more on that below) that implements the __except filter routine in C exception support, or the hardcoded value 0x1 to indicate that this is the __except filter unconditionally accepts the exception (this is also set to 0x1 for a __finally block). The JumpTarget member is the RVA of where control is transferred if the C exception handler indicates the address of the body of an __except block (or a __finally block).

6. The C exception handler routine whose RVA is given by the HandlerAddress of the C scope table for a code block is defined as follows:

   typedef
   LONG
   (NTAPI * PC_LANGUAGE_EXCEPTION_HANDLER)(
      __in    PEXCEPTION_POINTERS    ExceptionPointers,
      __in    ULONG64                EstablisherFrame
      );

   The ExceptionPointers argument is the familiar EXCEPTION_POINTERS structure that the GetExceptionInformation macro returns. The EstablisherFrame argument contains the stack pointer value for the routine associated with the C exception handler in question at the point in which the exception occured. (If the exception occured in a subfunction called by the function that the exception is now being inspected at, then the stack pointer should be relative to the point just after the call to the faulting function was made.) The EstablisherFrame argument is typically used to allow transparent access to the local variables of the current function from within the exception filter, even though technically the exception filter is not part of the current function but actually a completely different function itself. This is the mechanic by which you can access local variables within an __except expression.
   The function definition deserves a bit more explanation than just the parameter value meanings, however, as it is really dual-purpose. There are two modes for this routine, exception handling mode and unwind handling mode. If the low byte of the ExceptionPointers argument is set to the hardcoded value 0x1, then the handler is being called for an unwind operation. In this case, the rest of the ExceptionPointers argument is meaningless, and only the EstablisherFrame argument holds a meaningful value. In addition, when operating in unwind mode, the return value of the exception handler routine is ignored (the compiler often doesn’t even initialize it for that code path). In exception handling mode (where the ExceptionPointers argument’s low byte is not equal to the hardcoded value 0x1), both arguments are significant, and the return value is also used. In this case, the return value is one of the familiar EXCEPTION_EXECUTE_HANDLER, EXCEPTION_CONTINUE_SEARCH, and EXCEPTION_CONTINUE_EXECUTION constants that are returned by an __except filter expression. If EXCEPTION_EXECUTE_HANDLER is returned, then control will eventually be transferred to the JumpTarget member of the current scope table entry.

7. The definition of the UNWIND_HISTORY_TABLE structure (and associated substructures) for x64 is as follows (this structure is used as a cache to speed up repeated exception handling lookups, and is typically optional as far as usage with RtlUnwindEx goes – though certainly recommended from a performance perspective):

   #define UNWIND_HISTORY_TABLE_SIZE 12
   
   typedef struct _UNWIND_HISTORY_TABLE_ENTRY {
           ULONG64           ImageBase;
           PRUNTIME_FUNCTION FunctionEntry;
   } UNWIND_HISTORY_TABLE_ENTRY,
   *PUNWIND_HISTORY_TABLE_ENTRY;
   
   #define UNWIND_HISTORY_TABLE_NONE 0
   #define UNWIND_HISTORY_TABLE_GLOBAL 1
   #define UNWIND_HISTORY_TABLE_LOCAL 2
   
   typedef struct _UNWIND_HISTORY_TABLE {
           ULONG                      Count;
           UCHAR                      Search;
           ULONG64                    LowAddress;
           ULONG64                    HighAddress;
           UNWIND_HISTORY_TABLE_ENTRY
              Entry[ UNWIND_HISTORY_TABLE_SIZE ];
   } UNWIND_HISTORY_TABLE, *PUNWIND_HISTORY_TABLE;

8. There are inconsistencies regarding the usage of RUNTIME_FUNCTION and IMAGE_RUNTIME_FUNCTION in various places in the documentation. These two structures are synonymous for x64 and may be used interchangeably.

Most of the other x64 exception handling information on the latest version of MSDN is correct (specifically, parts dealing with dealing with function tables, such as RtlLookupFunctionTableEntry.) Remember that the MSDN documentation also includes IA64 definitions on the same page, though (and the IA64 definition is typically the one presented at the top with all of the arguments explained, where you would expect it). You’ll typically need to scroll through the remarks section to find information on the x64 versions of these routines. Be wary of using your locally installed Platform SDK help with the functions that are correctly documented on MSDN, though, as to my knowledge only the very latest SDK version (e.g. the Vista SDK) actually has correct information for any of the x64 exception handling information; older versions, such as the Platform SDK that shipped with Visual Studio 2005, only include IA64 information for routines like RtlVirtualUnwind or RtlLookupFunctionTableEntry. In general, anywhere you see a reference to a FRAME_POINTERS or Gp structure or value in the documentation, this is a good hint that the documentation is talking exclusively about IA64 and does not directly apply to x64.

That’s all for this installment. More on how to use this information from a programmatic perspective next time…

This entry was posted on Wednesday, December 13th, 2006 at 11:38 am and is filed under NT Internals, Programming, Windows. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.